CosNaming Module
BindingIterator Interface
NamingContext Interface
The Naming Service provides a mapping between names and objects. It provides for persistent storage of name-object mappings, which are called name bindings.
The Naming Service also provides a mechanism for resolving an object by name. The name bindings are stored in a distributed collection of naming contexts. This is analogous to a hierarchical directory structure such as that found on UNIX. The naming contexts are analogous to UNIX directories and are organized as a directed graph.
The Naming Service provides for construction of the naming context graph by allowing binding of naming context objects into other naming context objects. This is analogous to creating UNIX directories within other UNIX directories.
The Naming Service provides for a syntax-independent representation of names.
The Naming Service interfaces are contained in the CosNaming module. The module provides a namespace for declarations common to the Naming Service interfaces.
typedef string Istring;
struct NameComponent
{
Istring id;
Istring kind;
};
typedef sequence <NameComponent> Name;
enum BindingType {nobject, ncontext};
struct Binding
{
Name binding_name;
BindingType binding_type;
};
typedef sequence <Binding> BindingList;
interface BindingIterator {};
interface NamingContext {};
|
The CORBA Naming Service is made up of two basic interfaces:
NamingContext
BindingIterator
Because the NamingContext and the BindingIterator are both CORBA interfaces, they are accessed via object references and are distributed. The NamingContext contains named object references or other named items. It is similar to a directory that can contain named files or other named directories.
The BindingIterator is used to iterate across object references contained within a particular NamingContext. It provides a way to get the number of named object references within a NamingContext. It also provides a next_one and a next_n method to retrieve individual named object references or contexts.
The following method returns the next binding. If there are no more bindings, false is returned.
boolean next_one(out Binding <b>);
The following method returns the number of bindings specified by the <how_many> parameter. If there are no more bindings, false is returned.
boolean next_n(in unsigned long <how_many>, out BindingList <bl>);
The following method destroys the iterator.
void destroy( );
The NamingContext interface does the following:
The following method binds a name and objects. This type of binding does not participate in name resolution when compound names are passed for resolution.
void bind(in Name <n>, in Object <obj>) raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
When Name is a composed of more than one component, all components except the last are used to resolve the naming context to which this binding will be added. The final component is associated with the object specified in the argument obj and is used to retrieve the object with a call to resolve( ).
The following method binds a name and an object in the naming context even if the name is already bound in that naming context.
void rebind(in Name <n>, in Object <obj>) raises(NotFound, CannotProceed, InvalidName);
The previous name is replaced by the new name. This type of binding does not participate in name resolution when compound names are passed to be resolved.
The following method binds a name and a naming context. This type of naming context participates in name resolution when compound names are passed to be resolved.
void bind_context(in Name <n>, in NamingContext <nc>) raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
This method binds a name and a naming context (specified by <nc>) even if the name is already bound in the context.
void rebind_context(in Name <n>, in NamingContext <nc>) raises(NotFound, CannotProceed, InvalidName);
The previously used name is unbound and replaced by <nc>. This type of binding participates in name resolution when compound names are passed to be resolved.
This method returns the object bound to the specified name in a given naming context.
Object resolve(in Name <n>,) raises(NotFound, CannotProceed, InvalidName);
The name specified by the parameter <n> must match exactly. The Naming Service does not return the type of the object. Clients are responsible for narrowing the object to the appropriate type. Clients typically cast the returned object to a more specialized interface.
The following method removes a name binding from a naming context.
void unbind(in Name <n>) raises(NotFound, CannotProceed, InvalidName);
The following method returns a naming context object contained by the same naming server as the context on which the operation was invoked.
NamingContext new_context( );
The new_context is not bound to any name.
This method creates a new context and binds it to the name specified by the <n> argument.
NamingContext bind_new_context(in Name <n>) raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
The newly created naming context object is contained by the same naming server as the naming context to which it was bound.
This method deletes a naming context.
void destroy( ) raises(NotEmpty);
The naming context on which the method is invoked must not contain any bindings.
The following method allows the client to iterate through a set of bindings in a naming context.
void list(in unsigned long <how_many>, out BindingList <bl>, out BindingIterator <bi>);
The list( ) method returns at most the requested number of bindings specified by the <how_many> argument. The return value is in the <bl> argument. If the naming context contains additional bindings, the list( ) method returns the additional bindings in the <bi> parameter. If there are no additional bindings, <bi> is a nil object reference.
This section describes the exceptions that can occur when using the CORBA Naming Server.
The following exception is raised when some component of the specified name is not bound.
enum NotFoundReason {missing_node, not_context, not_object}
exception NotFound
{
NotFoundReason <why>;
Name <rest_of_name>;
};
The <why> argument contains the component that could not be resolved. The rest of the name is returned.
This exception occurs if, for some reason, the invoked method cannot complete its operation.
exception CannotProceed
{
NamingContext <ctx>;
Name <rest_of_name>;
};
This exception is raised when a Name argument is invalid. A Name is invalid if it is zero length.
exception InvalidName { };
exception AlreadyBound { };
An object can only be bound to one name in a given naming context. An attempt to create another binding without first releasing an object already bound raises this exception.
A naming context cannot be destroyed while it has any name bindings in it. This exception is raised when there is an attempt to destroy the naming context while there are one or more object bindings.
exception NotEmpty { };