/* * 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.
* * See http://www.omg.org/technology/documents/formal/naming_service.htm * for the complete CORBA * COS Naming Specification.
*/ 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.
* * 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.
*
* 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
*
* @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.
*
* See
* CORBA COS
* Naming Specification.
*/
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.
*
* The list operation returns at most the requested number of
* bindings in BindingList bl.
*
*
* @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);
};
/**
*
*
* See
* CORBA COS
* Naming Specification.
*/
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);
};
};
*
*
* @param how_many the maximum number of bindings to return NamingContextExt
is the extension of NamingContext
* 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 NamingContextExt, you can use
* URL-based names to bind and resolve.