// CosNaming.idl
// pre-process command line (java):
// idl2java -DJAVA -package org.omg CosNaming.idl
// pre-process command line (C++):
// idl2cpp -exportName_Export -corba_incname_def.h -type_code_info -client_ext_c -server_ext_s CosNaming.idl
//
// Source: ptc/99-12.04

// File: CosNaming.idl
#ifndef _COSNAMING_IDL_
#define _COSNAMING_IDL_

#pragma prefix "omg.org"

module CosNaming {
    typedef string Istring;

    /**
      A name component consists of two attributes: the identifier attribute, 
      id, and the kind attribute, kind.
	  <p>
      Based on the INS specification, ISO Latin-1 characters, excluding the 
      ASCII NULL characters are allowed for ID and Kind field of a 
	  NameComponent. The VisiBroker Naming Service constraints it further 
	  by allowing only printable characters for ID and Kind field. 
	  Furthermore, the length of both the ID and Kind fields cannot exceed 
	  255 characters. And null string is not allowed. 
	  </p>
	  <p>
      When comparing two NameComponents for equality both id and kind field
      must match in order for two NameComponents to be considered identical. 
      This applies for zero-length fields as well. Name comparisons are case 
      sensitive.
	  </p>
   */
    struct NameComponent {
        Istring id;
        Istring kind;
    };

    /**
      A name is a sequence of NameComponents. The empty sequence is not a
      legal name. When comparing Names for equality, each NameComponent in
      the first Name must match the corresponding NameComponent in the
      second Name for the Names to be considered identical.
    */
    typedef sequence<NameComponent> Name;

    /**
      The value of binding_type is ncontext if a Name denotes a binding
      created with one of the following operations:
      <ul>
      <li> bind_context
      <li> rebind_context
      <li> bind_new_context
      </ul>
      For bindings created with any other operation, the value of
      binding_type is nobject.
    */
    enum BindingType { nobject, ncontext };
    struct Binding {
        Name        binding_name;
        BindingType binding_type;                   
    };

    // Note: In struct Binding, binding_name is incorrectly defined
    // as a Name instead of a NameComponent. This definition is
    // unchanged for compatibility reasons.
    typedef sequence <Binding> BindingList;                     

    interface BindingIterator;

    interface NamingContext {
        /**
          The NotFound exception is raised by operations when a component of a 
		  name does not identify a binding or the type of the binding is
          incorrect for the operation being performed. The why member
          explains the reason for the exception and the rest_of_name member
          contains the remainder of the non-working name:
          <ul>
          <li>missing_node
             The first name component in rest_of_name denotes a binding
             that is not bound under that name within its parent context.
          <li>not_context
             The first name component in rest_of_name denotes a binding with
             a type of nobject when the type ncontext was required.
          <li>not_object
             The first name component in rest_of_name denotes a binding with
             a type of ncontext when the type nobject was required.
          </ul>
          */
        enum NotFoundReason { missing_node, not_context, not_object };
        exception NotFound { 
            NotFoundReason  why;
            Name            rest_of_name;
        };

      /**
		This exception is raised when an implementation has given up for 
		some reason.  The client, however, may be able to continue the 
		operation at the returned naming context. The cxt member contains 
		the context that the operation may be able to retry from. The 
		rest_of_name member contains the remainder of the non-working name.
		*/
        exception CannotProceed {
            NamingContext   cxt;
            Name            rest_of_name;
        };

		/**
		  This exception is raised if a Name is invalid. A name of length
		  zero is invalid (containing no name components). 
		  */
        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 {};

		/**
		  This exception is raised by destroy if the NamingContext contains
		  bindings. A NamingContext must be empty to be destroyed.
		  */
        exception NotEmpty{};

		/**
		  Creates an nobject binding in the naming context.
		  */
        void    bind(in Name n, in Object obj)      
                    raises(
                        NotFound, CannotProceed, InvalidName, AlreadyBound
                    );

		/**
		  Creates an nobject binding in the naming context even if the name
		  is already bound in the context. If already bound, the previous
		  binding must be of type nobject; otherwise, a NotFound exception
		  with a why reason of not_object is raised.
		  */
        void    rebind(in Name n, in Object obj)    
                    raises(NotFound, CannotProceed, InvalidName);

		/**
		  Creates an ncontext binding in the parent naming context. Attempts
		  to bind a nil context raise a BAD_PARAM exception.
		  */
        void    bind_context(in Name n, in NamingContext nc)        
                    raises(NotFound, CannotProceed, InvalidName, AlreadyBound);

		/**
		  Creates an ncontext binding in the naming context even if the name
		  is already bound in the context. If already bound, the previous
		  binding must be of type ncontext; otherwise, a NotFound exception
		  with a why reason of not_context will be raised.
		  */
        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.
		  Names can have multiple components; therefore, name resolution can
		  traverse multiple contexts. These contexts can be federated
		  between different Naming Service instances.
		  */
        Object  resolve (in Name n)
                    raises(NotFound, CannotProceed, InvalidName);

		/**
		  The unbind operation removes a name binding from a context.
		  */
        void    unbind(in Name n)
                raises(NotFound, CannotProceed, InvalidName);

		/**
		  This operation returns a new naming context. The new context is
		  not bound to any name.
		  */
        NamingContext   new_context();

		/**
		  This operation creates a new context and creates an ncontext
		  binding for it using the name supplied as an argument.
		  */
        NamingContext   bind_new_context(in Name n)
                            raises(
                                NotFound, AlreadyBound,
                                CannotProceed, InvalidName
                            );

		/**
		  This operation destroys its naming context. If there are bindings
		  denoting the destroyed context, these bindings are not removed. If
		  the naming context contains bindings, the operation raises
		  NotEmpty.
		  */
        void    destroy() raises(NotEmpty);

		/**
		  The list operation allows a client to iterate through a set of
		  bindings in a naming context.
		  <p>
		  list returns the bindings contained in a context in the parameter
		  bl. The bl parameter is a sequence where each element is a Binding
		  containing a Name of length 1 representing a single NameComponent.
		  </p>
		  <p>
		  The how_many parameter determines the maximum number of bindings
		  to return in the parameter bl, with any remaining bindings to be
		  accessed through the returned BindingIterator bi. 
		  </p>
		  <ul>
		  <li>A non-zero
		  value of how_many guarantees that bl contains at most how_many
		  elements. The implementation is free to return fewer than the
		  number of bindings requested by how_many. However, for a non-zero
		  value of how_many, it may not return a bl sequence with zero
		  elements unless the context contains no bindings. 
		  <li>If how_many
		  is set to zero, the client is requesting to use only the
		  BindingIterator bi to access the bindings and list returns a zero
		  length sequence in bl.
		  <li>The parameter bi returns a reference to an iterator object.
		  <li>If the bi parameter returns a non-nil reference, this indicates
		  that the call to list may not have returned all of the bindings in
		  the context and that the remaining bindings (if any) must be
		  retrieved using the iterator. This applies for all values of
		  how_many. 
		  <li>If the bi parameter returns a nil reference, this
		  indicates that the bl parameter contains all of the bindings in
		  the context. This applies for all values of how_many.
		  </ul>
		  */
        void    list(
                    in unsigned long    how_many,
                    out BindingList     bl,
                    out BindingIterator bi
                );

    };

	/**
	  The BindingIterator interface allows a client to iterate through the
	  bindings using the next_one or next_n operations.
	  */
    interface BindingIterator {
		/**
		  The next_one operation returns the next binding. It returns true
		  if it is returning a binding, false if there are no more bindings
		  to retrieve. If next_one returns false, the returned Binding is
		  indeterminate.
		  <p>Further calls to next_one after it has returned
		  false have undefined behavior.
		  </p>
		  */
        boolean next_one(out Binding b);

		/**
		  next_n returns, in the parameter bl, bindings not yet retrieved
		  with list or previous calls to next_n or next_one. It returns true
		  if bl is a non-zero length sequence; it returns false if there are
		  no more bindings and bl is a zero-length sequence.
		  <p>
		  The how_many parameter determines the maximum number of bindings
		  to return in the parameter bl:
		  <ul>
		  <li>A non-zero value of how_many guarantees that bl contains at
		  most how_many elements. The implementation is free to return fewer
		  than the number of bindings requested by how_many. However, it may
		  not return a bl sequence with zero elements unless there are no
		  bindings to retrieve.
		  <li>A zero value of how_many is illegal and raises a BAD_PARAM
		  system exception.
		  </ul>
		  next_n returns false with a bl parameter of length zero once all
		  bindings have been retrieved. Further calls to next_n after it has
		  returned a zero-length sequence have undefined behavior.
		  */
        boolean next_n(in unsigned long how_many, out BindingList bl);

		/**
		  The destroy operation destroys its iterator. If a client invokes
		  any operation on an iterator after calling destroy, the operation
		  raises OBJECT_NOT_EXIST.
		  */
        void    destroy();
    };


	/**
	  The NamingContextExt interface, derived from NamingContext, provides
	  the operations required to use URLs and stringified names.
	  */
    interface NamingContextExt: NamingContext {
        typedef string StringName;
        typedef string Address;
        typedef string URLString;

		/**
		  This operation accepts a Name and returns a stringified name. If
		  the Name is invalid, an InvalidName exception is raised.
		  */
        StringName  to_string(in Name n) raises(InvalidName);

		/**
		  This operation accepts a stringified name and returns a Name. If
		  the stringified name is syntactically malformed or violates an
		  implementation limit, an InvalidName exception is raised.
		  */
        Name        to_name(in StringName sn) 
                        raises(InvalidName);

        exception InvalidAddress {};

		/**
		  This operation takes a corbaloc URL <address> and <key_string>
		  component such as:
		  <ul>
		  <li>:myhost.555xyz.com
		  <li>:myhost.555xyz.com/a/b/c
		  <li>atm:00002112...,:myhost.xyz.com/a/b/c
		  </ul>
		  for the first parameter, and a stringified name for the second. It
		  then performs any escapes necessary on the parameters and returns
		  a fully formed URL string. An exception is raised if either the
		  corbaloc address and key parameter or name parameter are
		  malformed.
		  <p>It is legal for the stringified_name to be empty. If the
		  address is empty, an InvalidAddress exception is raised.
		  </p>
		  */
        URLString   to_url(in Address addr, in StringName sn)
                        raises(InvalidAddress, InvalidName);

		/**
		  This is a convenience operation that performs a resolve in the
		  same manner as NamingContext::resolve. It accepts a stringified
		  name as an argument instead of a Name.
		  */
        Object      resolve_str(in StringName n)
                        raises(
                            NotFound, CannotProceed,
                            InvalidName
                        );
    };
};

#endif // _COSNAMING_IDL_