corba/src/share/classes/org/omg/CosNaming/nameservice.idl

/*
 * Copyright (c) 1996, 2010, 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.
   * 
   * 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/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 <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>
 * 
 * @param 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);
    
  };


/** 
 * <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
 * contexts at the same time. Using <tt>NamingContextExt</tt>, you can use
 * URL-based names to bind and resolve. <p>
 * 
 * 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 <p>
 * 
 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
 * Indicates the name does not identify a binding.<p>
 * 
 */ 
	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 <p>
 * 
 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
 * Indicates the name does not identify a binding.<p>
 * 
 */ 
	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 <p>
 * @param sn Stringified Name of the object <p>
 * 
 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
 * Indicates the name does not identify a binding.<p>
 * @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress
 * Indicates the internet based address of the host machine is 
 * incorrect <p>
 * 
 */ 
	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 <p>
 * 
 * @exception org.omg.CosNaming.NamingContextPackage.NotFound
 * Indicates there is no object reference for the given name. <p>
 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
 * Indicates that the given compound name is incorrect <p>
 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
 * Indicates the name does not identify a binding.<p>
 * 
 */ 
	Object resolve_str( in StringName sn)
		raises( NotFound, CannotProceed,
			InvalidName);

  };

};