jdk8-mips64-public/corba: src/share/classes/org/omg/CosNaming/nameservice.idl@f90b3e014e83 (annotated)

src/share/classes/org/omg/CosNaming/nameservice.idl@f90b3e014e83 (annotated)

src/share/classes/org/omg/CosNaming/nameservice.idl

Tue, 28 Dec 2010 15:52:36 -0800

author: ohair
date: Tue, 28 Dec 2010 15:52:36 -0800
changeset 240: f90b3e014e83
parent 158: 91006f157c46
child 748: 6845b95cba6b
permissions: -rw-r--r--

6962318: Update copyright year
Reviewed-by: xdono

 /*
  * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
 // name.idl - Naming service interface
 #pragma prefix "omg.org"
 /**
  * The CORBA COS Naming Service provides the ability to bind a name
  * to an object relative to a naming context. A naming context is an
  * object that contains a set of name bindings in which each name is unique.
  * To resolve a name is to determine the object associated with the name in
  * a given context. <p>
  *
  * See http://www.omg.org/technology/documents/formal/naming_service.htm
  * for the complete CORBA
  * COS Naming Specification. <p>
  */
 module CosNaming
 {
   typedef string Istring;
   /**
    * Many of the operations defined on a naming context take names as
    * parameters. Names have structure. A name is an ordered sequence of
    * components. <p>
    *
    * A name with a single component is called a simple name; a name with
    * multiple components is called a compound name. Each component except
    * the last is used to name a context; the last component denotes the
    * bound object. <p>
    *
    * A name component consists of two attributes: the identifier
    * attribute and the kind attribute. Both the identifier attribute and the
    * kind attribute are represented as IDL strings. The kind attribute adds
    * descriptive power to names in a syntax-independent way. Examples of the
    * value of the kind attribute include c_source, object_code, executable,
    * postscript, or " ".
    */
   struct NameComponent
   {
     Istring id;
     Istring kind;
   };
   /**
    * A name is a sequence of name components.
    */
   typedef sequence <NameComponent> Name;
   /**
    * Specifies whether the given binding is for a object (that is not a
    * naming context) or for a naming context.
    */
   enum BindingType
   {
     nobject, 	// name is bound to an object
     ncontext	// name is bound to a naming context
   };
   /**
    * A name-to-object association is called a Binding.
    */
   struct Binding
   {
     Name binding_name; 		// name
     BindingType binding_type;	// whether name is bound to an object
                                 //  or a naming context
   };
   /**
    * List of Bindings.
    */
   typedef sequence <Binding> BindingList;
   /**
    * The BindingIterator interface allows a client to iterate through
    * the bindings using the next_one or next_n operations.
    *
    * The bindings iterator is obtained by using the <tt>list</tt>
    * method on the <tt>NamingContext</tt>.
    * @see org.omg.CosNaming.NamingContext#list
    */
   interface BindingIterator
   {
     /**
      * This operation returns the next binding. If there are no more
      * bindings, false is returned.
      *
      * @param b the returned binding
      */
     boolean next_one(out Binding b);
     /**
      * This operation returns at most the requested number of bindings.
      *
      * @param how_many the maximum number of bindings tro return <p>
      *
      * @param bl the returned bindings
      */
     boolean next_n(in unsigned long how_many,
 		   out BindingList bl);
     // Destroy binding iterator
     /**
      * This operation destroys the iterator.
      */
     void destroy();
   };
 /**
  * A naming context is an object that contains a set of name bindings in
  * which each name is unique. Different names can be bound to an object
  * in the same or different contexts at the same time. <p>
  *
  * See <a href="http://www.omg.org/technology/documents/formal/naming_service.htm">
  * CORBA COS
  * Naming Specification.</a>
  */
     interface NamingContext
     {
         // Declare exceptions
         /**
          * Indicates the reason for not able to resolve.
          */
         enum NotFoundReason
         {
             missing_node,
             not_context,
             not_object
         };
 /**
  * Indicates the name does not identify a binding.
  */
         exception NotFound
         {
             NotFoundReason why;
             Name rest_of_name;
         };
 /**
  * Indicates that the implementation has given up for some reason.
  * The client, however, may be able to continue the operation at the
  * returned naming context.
  */
         exception CannotProceed
         {
             NamingContext cxt;
             Name rest_of_name;
         };
 /**
  * Indicates the name is invalid.
  */
         exception InvalidName
         {};
 /**
  * Indicates an object is already bound to the specified name. Only
  * one object can be bound to a particular name in a context.
  */
         exception AlreadyBound
         {};
 /**
  * Indicates that the Naming Context contains bindings.
  */
         exception NotEmpty
         {};
 /**
  * Creates a binding of a name and an object in the naming context.
  * Naming contexts that are bound using bind do not participate in name
  * resolution when compound names are passed to be resolved.
  *
  * @param n Name of the object <p>
  *
  * @param obj The Object to bind with the given name<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates
  * the name does not identify a binding.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
  * Indicates that the implementation has given up for some reason.
  * The client, however, may be able to continue the operation
  * at the returned naming context.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidName
  * Indicates that the name is invalid. <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound
  * Indicates an object is already bound to the specified name.<p>
  */
         void bind(in Name n,
 	      in Object obj)
         raises(NotFound,
 	     CannotProceed,
 	     InvalidName,
 	     AlreadyBound);
 /**
  * Names an object that is a naming context. Naming contexts that
  * are bound using bind_context() participate in name resolution
  * when compound names are passed to be resolved.
  *
  * @param n Name of the object <p>
  *
  * @param nc NamingContect object to bind with the given name <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
  * given up for some reason. The client, however, may be able to
  * continue the operation at the returned naming context.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
  * bound to the specified name.<p>
  */
     void bind_context(in Name n,
 		      in NamingContext nc)
       raises(NotFound,
 	     CannotProceed,
 	     InvalidName,
 	     AlreadyBound);
 /**
  * Creates a binding of a name and an object in the naming context
  * even if the name is already bound in the context. Naming contexts
  * that are bound using rebind do not participate in name resolution
  * when compound names are passed to be resolved.
  *
  * @param  n Name of the object <p>
  *
  * @param obj The Object to rebind with the given name <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
  * given up for some reason. The client, however, may be able to
  * continue the operation at the returned naming context.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
  */
     void rebind(in Name n,
 		in Object obj)
       raises(NotFound,
 	     CannotProceed,
 	     InvalidName);
 /**
  * Creates a binding of a name and a naming context in the naming
  * context even if the name is already bound in the context. Naming
  * contexts that are bound using rebind_context() participate in name
  * resolution when compound names are passed to be resolved.
  *
  * @param n Name of the object <p>
  *
  * @param nc NamingContect object to rebind with the given name <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
  * given up for some reason. The client, however, may be able to
  * continue the operation at the returned naming context.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
  */
     void rebind_context(in Name n,
 			in NamingContext nc)
       raises(NotFound,
 	     CannotProceed,
 	     InvalidName);
 /**
  * The resolve operation is the process of retrieving an object
  * bound to a name in a given context. The given name must exactly
  * match the bound name. The naming service does not return the type
  * of the object. Clients are responsible for "narrowing" the object
  * to the appropriate type. That is, clients typically cast the returned
  * object from Object to a more specialized interface.
  *
  * @param n Name of the object <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
  * given up for some reason. The client, however, may be able to
  * continue the operation at the returned naming context.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
  */
     Object resolve(in Name n)
       raises(NotFound,
 	     CannotProceed,
 	     InvalidName);
 /**
  * The unbind operation removes a name binding from a context.
  *
  * @param n Name of the object <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
  * given up for some reason. The client, however, may be able to
  * continue the operation at the returned naming context.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
  */
     void unbind(in Name n)
       raises(NotFound,
 	     CannotProceed,
 	     InvalidName);
 /**
  * The list operation allows a client to iterate through a set of
  * bindings in a naming context. <p>
  *
  * The list operation returns at most the requested number of
  * bindings in BindingList bl.
  * <ul>
  * <li>If the naming context contains additional
  * bindings, the list operation returns a BindingIterator with the
  * additional bindings.
  * <li>If the naming context does not contain additional
  * bindings, the binding iterator is a nil object reference.
  * </ul>
  *
  * @param how_many the maximum number of bindings to return <p>
  *
  * @param bl the returned list of bindings <p>
  *
  * @param bi the returned binding iterator <p>
  */
     void list(in unsigned long how_many,
 	      out BindingList bl,
 	      out BindingIterator bi);
 /**
  * This operation returns a naming context implemented by the same
  * naming server as the context on which the operation was invoked.
  * The new context is not bound to any name.
  */
     NamingContext new_context();
 /**
  * This operation creates a new context and binds it to the name
  * supplied as an argument. The newly-created context is implemented
  * by the same naming server as the context in which it was bound (that
  * is, the naming server that implements the context denoted by the
  * name argument excluding the last component).
  *
  * @param n Name of the object <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
  * bound to the specified name.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
  * given up for some reason. The client, however, may be able to
  * continue the operation at the returned naming context.<p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
  */
     NamingContext bind_new_context(in Name n)
       raises(NotFound,
 	     AlreadyBound,
 	     CannotProceed,
 	     InvalidName);
 /**
  * The destroy operation deletes a naming context. If the naming
  * context contains bindings, the NotEmpty exception is raised.
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotEmpty Indicates that the Naming Context contains bindings.
  */
     void destroy()
       raises(NotEmpty);
   };
 /**
  * <code>NamingContextExt</code> is the extension of <code>NamingContext</code>
  * which
  * contains a set of name bindings in which each name is unique and is
  * part of Interoperable Naming Service.
  * Different names can be bound to an object in the same or different
  * contexts at the same time. Using <tt>NamingContextExt</tt>, you can use
  * URL-based names to bind and resolve. <p>
  *
  * See <a href="http://www.omg.org/technology/documents/formal/naming_service.htm">
  * CORBA COS
  * Naming Specification.</a>
  */
   interface NamingContextExt: NamingContext
    {
 /**
  * StringName is the Stringified Name, Array of Name Components
  * represented as a String.
  */
 	typedef string StringName;
 /**
  * Address is the Host and Port information represented as a String.
  */
 	typedef string Address;
 /**
  * URLString is the URL address (corbaloc: or corbaname:) represented as
  * a String.
  */
 	typedef string URLString;
 /**
  * This operation creates a stringified name from the array of Name
  * components.
  *
  * @param n Name of the object <p>
  *
  * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
  * Indicates the name does not identify a binding.<p>
  *
  */
 	StringName to_string( in Name n ) raises (InvalidName);
 /**
  * This operation  converts a Stringified Name into an  equivalent array
  * of Name Components.
  *
  * @param sn Stringified Name of the object <p>
  *
  * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
  * Indicates the name does not identify a binding.<p>
  *
  */
 	Name to_name( in StringName sn ) raises (InvalidName);
 /**
  * Indicates the invalid Stringified name for the object, The
  * reason could be invalid syntax.
  */
 	exception InvalidAddress
 	{ };
 /**
  * This operation creates a URL based "iiopname://" format name
  * from the Stringified Name of the object.
  *
  * @param addr internet based address of the host machine where  Name Service is running <p>
  * @param sn Stringified Name of the object <p>
  *
  * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
  * Indicates the name does not identify a binding.<p>
  * @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress
  * Indicates the internet based address of the host machine is
  * incorrect <p>
  *
  */
 	URLString to_url( in Address addr, in StringName sn )
 			raises( InvalidAddress, InvalidName );
 /**
  * This operation resolves the Stringified name into the object
  * reference.
  *
  * @param sn Stringified Name of the object <p>
  *
  * @exception org.omg.CosNaming.NamingContextPackage.NotFound
  * Indicates there is no object reference for the given name. <p>
  * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
  * Indicates that the given compound name is incorrect <p>
  * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
  * Indicates the name does not identify a binding.<p>
  *
  */
 	Object resolve_str( in StringName sn)
 		raises( NotFound, CannotProceed,
 			InvalidName);
   };
 };

Mercurial > jdk8-mips64-public > corba / annotate

src/share/classes/org/omg/CosNaming/nameservice.idl@f90b3e014e83 (annotated)

src/share/classes/org/omg/CosNaming/nameservice.idl