/* -*- 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.
    };
};