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