/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
*/
//
// CosNaming.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/corba/sectrans.htm#nam 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
  };
    
  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/corba/sectrans.htm#nam">CORBA COS 
   * Naming Specification.</a>
   */

  interface NamingContext 
  {
    // Declare exceptions
    /**
     * 
     */
    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>
     * 
     * @parm 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);
   }; 
  /**
   * A naming context extension is an extension to naming context 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/corba/sectrans.htm#nam">CORBA COS 
   * Naming Specification.</a>
   */

  interface NamingContextExt : CosNaming::NamingContext {

    typedef string StringName;
    typedef string Address;
    typedef string URLString;

  /** 
     * The to_string operation is the process of retrieving a stringified name 
     * from a name object. 
     * 
     * @param n String Name of the object <p>
     * 
     * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
     */ 
    StringName to_string(in Name n) 
      raises(
	NamingContext::InvalidName);

  /** 
     * The to_name operation is the process of retrieving a name object
     * to a stringified name. 
     * 
     * @param n String Name of the object <p>
     * 
     * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
     */ 
    Name to_name(in StringName sn)
      raises(NamingContext::InvalidName);


    exception InvalidAddress {};

  /** 
     * The to_url operation is the process of retrieving a url representation from a stringified name and
     * address.
     * 
     * @param addr Address of the object <p>
     * 
     * @param sn String Name of the object <p>
     * 
     * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
     * 
     * @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress Indicates that the Address is invalid. <p>
     */
     URLString to_url(in Address addr, in StringName sn)
       raises(
        InvalidAddress, 
        NamingContext::InvalidName);
    /** 
     * The resolve_str operation is the process of retrieving an object
     * bound to a stringified 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 String 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_str(in StringName n)
      raises(
         NamingContext::NotFound, 
         NamingContext::CannotProceed,
         NamingContext::InvalidName);
   };
};