/*

 * Copyright (c) 1996, 2015, 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.

   * 

   * @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 to return

     * 

     * @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.

 * 

 * @param obj The Object to bind with the given name.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates

 * the name does not identify a binding.

 * 

 * @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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName 

 * Indicates that the name is invalid.

 *

 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound 

 * Indicates an object is already bound to the specified name.

 */ 

        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.

 * 

 * @param nc NamingContect object to bind with the given name.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.

 * 

 * @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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.

 *

 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already 

 * bound to the specified name.

 */ 

    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.

 * 

 * @param obj The Object to rebind with the given name.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.

 * 

 * @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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.

 */ 

    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.

 * 

 * @param nc NamingContect object to rebind with the given name.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.

 * 

 * @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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.

 */ 

    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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.

 * 

 * @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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.

 */ 

    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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.

 * 

 * @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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.

 */ 

    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.

 * 

 * @param bl the returned list of bindings.

 * 

 * @param bi the returned binding iterator.

 */ 

    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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already 

 * bound to the specified name.

 * 

 * @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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.

 */ 

    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

 * URL-based names to bind and resolve.

 * 

 * 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.

 * 

 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName

 * Indicates the name does not identify a binding.

 * 

 */ 

        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.

 * 

 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName

 * Indicates the name does not identify a binding.

 * 

 */ 

        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.

 * @param sn Stringified Name of the object.

 * 

 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName

 * Indicates the name does not identify a binding.

 * @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress

 * Indicates the internet based address of the host machine is incorrect

 */

        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.

 * 

 * @exception org.omg.CosNaming.NamingContextPackage.NotFound

 * Indicates there is no object reference for the given name.

 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed

 * Indicates that the given compound name is incorrect.

 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName

 * Indicates the name does not identify a binding.

 * 

 */ 

        Object resolve_str( in StringName sn)

            raises( NotFound, CannotProceed,

            InvalidName);

  };