ChangeLogTag:Wed Dec 10 20:13:57 1997 Carlos O'Ryan <coryan@macarena.cs.wustl.edu>

1 files changed, 207 insertions, 0 deletions

diff --git a/TAO/orbsvcs/orbsvcs/CosNaming.idl b/TAO/orbsvcs/orbsvcs/CosNaming.idl
new file mode 100644
index 00000000000..770a2adea9f
--- /dev/null
+++ b/TAO/orbsvcs/orbsvcs/CosNaming.idl
@@ -0,0 +1,207 @@
+/* -*- C++ -*- */
+// $Id$
+
+// ============================================================================
+//
+// = LIBRARY
+//    cos
+// 
+// = FILENAME
+//    CosNaming.idl
+//
+// = AUTHOR
+//    Marina Spivak
+// 
+// ============================================================================
+
+module CosNaming
+  // = TITLE
+  // This module provides interface for using COS Naming Service.   
+{
+  typedef string Istring;
+  struct NameComponent 
+  {
+    Istring id;	
+    // This is the name that is used to identify object references.
+
+    Istring kind;	
+    // Stores any addtional info about the object reference.
+  };
+  // This is a 'simple' name.
+  // NOTE: both id and kind fields are used in resolving names.
+
+  typedef sequence <NameComponent> Name;
+  // This is a compound name: <c1; c2; c3; cn> where c1 to cn-1 are
+  // the names of the nested contexts, and cn is the name of the
+  // object bound in cn-1.
+
+  enum BindingType 
+  {
+    nobject,
+    // object binding.
+
+    ncontext
+    // naming context binding.
+  };
+
+  struct Binding 
+  {
+    Name    	binding_name;
+    BindingType	binding_type;                                  
+  };
+
+  typedef sequence <Binding> BindingList;
+
+  interface BindingIterator;
+  // Forward declaration.
+
+  interface NamingContext 
+    // = TITLE
+    // Interface for managing name bindings and naming contexts.
+    {
+      // = Exceptions.
+
+      enum NotFoundReason 
+      { 
+	missing_node,
+	not_context,
+	not_object
+      };
+        
+      exception NotFound 
+	{
+	  NotFoundReason why;
+	  Name rest_of_name;
+	};
+      // Indicates that the name does not identify a binding.
+
+      exception CannotProceed 
+	{
+	  //Commented out due to the bug in Orbix compiler               
+	  NamingContext cxt;
+	  Name rest_of_name;
+	};
+      // Implementation has given up for some reason.  The client,
+      // however, may be able to continue operation at the returned
+      // naming context.
+                                 
+      exception InvalidName {};                             
+      // A name of length 0 is invalid. 
+      // Implementations may place further restrictions.            
+                               
+      exception AlreadyBound {};
+      // Indicates that the specified name is already bound to some
+      // object.  Only one object can be bound to a particular name in
+      // a context.  To change the binding, <rebind> and
+      // <rebind_context> can be used.
+
+      exception NotEmpty {};
+      // Indicates that the context is not empty.
+
+      // = Binding operations.
+
+      void bind (in Name n, in Object obj)             
+	raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
+      // create a binding for name <n> and object <obj> in the naming
+      // context.  Compound names are treated as follows: ctx->bind
+      // (<c1; c2; c3; cn>, obj) = (ctx->resolve (<c1; c2;
+      // cn-1>))->bind (<cn>, obj) if the there already exists a
+      // binding for the specified name, <AlreadyBound> exception is
+      // thrown.  Naming contexts should be bound using <bind_context>
+      // and <rebind_context> in order to participate in name
+      // resolution later.
+
+      void rebind (in Name n, in Object obj)   
+	raises(NotFound, CannotProceed, InvalidName);
+      // this is similar to <bind> operation above, except for when
+      // the binding for the specified name already exists in the
+      // specified context.  In that case, the existing binding is
+      // replaced with the new one.
+		
+      void bind_context (in Name n, in NamingContext nc)               
+	raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
+      // This is the version of <bind> specifically for binding naming
+      // contexts, so that they will participate in name resolution
+      // when compound names are passed to be resolved.
+
+      void rebind_context (in Name n, in NamingContext nc)     
+	raises(NotFound, CannotProceed, InvalidName);
+      // This is a version of <rebind> specifically for naming
+      // contexts, so that they can participate in name resolution
+      // when compound names are passed.
+
+      // = Resolving names.
+
+      Object resolve (in Name n)
+	raises(NotFound, CannotProceed, InvalidName);
+      // Return object reference that is bound to the name.  Compound
+      // name resolve is defined as follows: ctx->resolve (<c1; c2;
+      // cn>) = ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The
+      // naming service does not return the type of the object.
+      // Clients are responsible for "narrowing" the object to the
+      // appropriate type.
+
+      // = Unbinding names.
+
+      void unbind (in Name n)
+	raises(NotFound, CannotProceed, InvalidName);
+      // Remove the name binding from the context.  When compound
+      // names are used, unbind is defined as follows: ctx->unbind
+      // (<c1; c2; cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind
+      // (<cn>)
+
+      // = Creating Naming Contexts.
+
+      NamingContext new_context ();
+      // This operation returns a new naming context implemented by
+      // the same naming server in which the operation was invoked.
+      // The context is not bound.
+
+      NamingContext bind_new_context (in Name n)
+	raises(NotFound, AlreadyBound, CannotProceed, InvalidName);
+      // 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 server as the context in which it was
+      // bound (the name argument excluding the last component).
+
+      // = Deleting contexts.
+
+      void destroy ()
+	raises (NotEmpty);
+      // Delete the naming context.  NOTE: the user should <unbind>
+      // any bindings in which the given context is bound to some
+      // names before invoking <destroy> operation on it.  Ignoring
+      // this rule may cause unexpected behaviour.  <destroy> deletes
+      // the context object if it is not bound to any names in the
+      // given address space.  <destroys> decrements the reference
+      // count of the context if bindings to it exist.
+		
+      // = Listing the naming context.
+		
+      void list (in unsigned long how_many, 
+		 out BindingList bl, out BindingIterator bi);
+      // Returns at most the requested number of bindings <how_many>
+      // in <bl>.  If the naming context contains additional bindings,
+      // they are returned with a BindingIterator.  In the naming
+      // context does not contain any additional bindings <bi>
+      // returned as null.
+    };
+
+  interface BindingIterator 
+    // = TITLE
+    // Interface for iterating over Bindings returned with the <list>
+    // operation.
+    {
+      boolean next_one (out Binding b);
+      // This operation returns the next binding.  If there are no
+      // more bindings false is returned.
+
+      boolean next_n (in unsigned long how_many, 
+		      out BindingList bl);
+      // This operation returns at most the requested number of
+      // bindings.
+
+      void destroy ();
+      // This operation destroys the iterator.
+    };
+};