Naming Service interfaces and classes (C++)

This section describes the interfaces and classes for the VisiBroker Naming Service (VisiNaming).

NamingContext

class _VISNMEXPORT NamingContext : public virtual CORBA_Object

This object is used to contain and manipulate a list of names that are bound to the VisiBroker ORB objects or to other NamingContext objects. Client applications use this interface to resolve or list all of the names within that context. Object implementations use this object to bind names to object implementations or to bind a name to a NamingContext object.

Include file

Include the file CosNaming_c.hh when using this class.

Code sample

The code sample below shows the IDL specification for the NamingContext.

module CosNaming {
interface NamingContext {
void bind(in Name n, in Object obj)
raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
void rebind(in Name n, in Object obj)
raises(NotFound, CannotProceed, InvalidName);
void bind_context(in Name n, in NamingContext nc)
raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
void rebind_context(in Name n, in NamingContext nc)
raises(NotFound, CannotProceed, InvalidName);
Object resolve(in Name n)
raises(NotFound, CannotProceed, InvalidName);
void unbind(in Name n)
raises(NotFound, CannotProceed, InvalidName);
NamingContext new_context();
NamingContext bind_new_context(in Name n)
raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
void destroy()
raises(NotEmpty);
void list(in unsigned long how_many,
out BindingList bl,
out BindingIterator bi);
};
};

NamingContext methods

virtual void bind(const Name& _n, CORBA::Object_ptr _obj);

If the parameter _n is a complex name, this method attempts to bind the specified Object to the specified Name by resolving the context associated with the first NameComponent and then binding the object to the new context using the following Name:

Name[NameComponent₂,...,
NameComponent_(n-1),NameComponent_n]

This recursive process of resolving and binding continues until the context associated with the NameComponent (n-1) is resolved and the actual name-to-object binding is stored. If parameter _n is a simple name, _obj will be bound to _n within this NamingContext.

Parameter	Description
_n	A Name, initialized with the desired name for the object.
_obj	The object to be bound.

This method may raise the following exceptions:.

Exception	Description
NotFound	The Name, or one of its components, could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned naming context.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.
AlreadyBound	The specified Name has already been bound to another object within the NamingContext.

virtual void rebind(const Name& _n, CORBA::Object_ptr _obj);

This method is exactly the same as the bind method, except that it never raises the AlreadyBound exception. If the specified Name has already been bound to another object, this method replaces that binding with the new binding.

Parameter	Description
_n	A Name structure, initialized with the desired name for the object.
_obj	The object to be rebound.

The following exceptions may be raised by this method.

Exception	Description
NotFound	The Name, or one of its components, could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned naming context.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

virtual void bind_context(const Name& _n, NamingContext_ptr _nc);

This method is identical to the bind method, except that it associates the supplied Name with a NamingContext, not an arbitrary VisiBroker ORB object.

Parameter	Description
_n	A Name structure initialized with the desired name for the naming context. The first (n-1) NameComponent structures in the sequence must resolve to a NamingContext.
_nc	The NamingContext object to be bound.

The following exceptions may be raised by this method.

Exception	Description
NotFound	The Name, or one of its components, could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned naming context.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.
AlreadyBound	The specified Name has already been bound to another object within the NamingContext.

virtual void rebind_context(const Name& _n, NamingContext_ptr _nc);

This method is exactly the same as the bind_context method, except that this method never raises the AlreadyBound exception. If the specified Name has already been bound to another naming context, this method replaces that binding with the new binding.

Parameter	Description
_n	A Name structure, initialized with the desired name for the object.
_nc	The NamingContext object to be rebound.

The following exceptions may be raised by this method.

Exception	Description
NotFound	The Name, or one of its components, could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned naming context.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

virtual CORBA::Object _ptr resolve(const Name& _n);

This method attempts to resolve the specified Name and return an object reference. If parameter _n is a simple name, it is resolved relative to this NamingContext.

If _n is a complex name, it is resolved using the context associated with the first NameComponent. Next, the new context to resolve the following Name:

Name[NameComponent₍₂₎,...,
NameComponent_(n-1),NameComponent_n]

This recursive process continues until the object associated with the nth NameComponent is returned.

Parameter	Description
_n	A Name structure, initialized with the name for the desired object.

The following exceptions may be raised by this method.

Exception	Description
NotFound	The Name, or one of its components, could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned naming context.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

virtual void unbind(const Name& _n);

This method performs the inverse operation of the bind method, removing the binding associated with the specified Name.

Parameter	Description
_n	A Name structure, initialized with the desired name to be unbound.

The following exceptions may be raised by this method.

Exception	Description
NotFound	The Name, or one of its components, could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned naming context.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

virtual NamingContext_ptr new_context();

This method creates a new naming context. The newly created context is implemented within the same server as this object. The new context is initially not bound to any Name.

virtual NamingContext_ptr bind_new_context(const Name& _n) raises ;

This method creates a new context and binds it to the specified Name within this Context.

Parameter	Description
_n	A Name structure, initialized with the specified Name for the newly created NamingContext object.

The following exceptions can be raised by this method.

Exception	Description
NotFound	The Name or one of its components could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned NamingContext.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.
AlreadyBound	The specified Name has already been bound to another object within the NamingContext.

virtual void destroy() ;

This method deactivates this naming context. Any subsequent attempt to invoke operations on this object raises a CORBA::OBJECT_NOT_EXIST runtime exception.

Before using this method, all Name objects that have been bound relative to this NamingContext should be unbound using the unbind method. Any attempt to destroy a NamingContext that is not empty raises a NotEmpty exception.

The following exceptions can be raised by this method.

Exception	Description
NotEmpty	The NamingContext to be destroyed is not empty.

virtual void list(CORBA::ULong _how_many, BindingList_out _bl,
BindingIterator_out _bi)

This method returns all of the bindings contained by this context. A maximum of _how_many Names are returned with the BindingList. Any left over bindings are returned via the BindingIterator. The returned BindingList and BindingIterator are described in detail in “Binding and BindingList” and can be used to navigate the list of names.

Parameter	Description
_how_many	The maximum number of Names to be returned.
_bl	A list of Names returned to the caller. The number of names in the list will not exceed how_many.
_bi	An iterator for use in traversing the rest of the Names.

NamingContextExt

class _VISNMEXPORT NamingContextExt : public virtual NamingContext, public virtual CORBA_Object

The NamingContextExt interface, which extends NamingContext, provides the operations required to use stringified names and URLs.

Include file

Included the naming file CosNaming_c.hh when you use this class.

Code sample

This code sample shows the IDL Specification for the NamingContextExt interface.

module CosNaming {
interface NamingContextExt {
typedef string StringName;
typedef string Address;
typedef string URLString;
StringName to_string(in Name n)
raises(InvalidName);
Name to_name(in StringName sn)
raises(InvalidName);
exception InvalidAddress {};
URLString to_url(in Address addr, in StringName sn)
raises(InvalidAddress, InvalidName);
Object resolve_str(in StringName n)
raises(NotFound, CannotProceed, InvalidName);
};
};

NamingContextExt methods

virtual char* to_string(const Name& _n);

This operation returns the stringified representation of the specified Name.

Parameter	Description
_n	A Name structure initialized with the desired name for object.

The following exception can be raised by this method.

Exception	Description
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

virtual Name* to_name(const char* _sn);

This operation returns a Name object for the specified stringified name.

Parameter	Description
_sn	The stringified name of an object.

The following exceptions can be raised by this method.

Exception	Description
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

virtual char* to_url(const char* _addr, const char* _sn);

This operation returns a fully-formed string URL using the URL specified in _addr and the stringified name in _sn.

Parameter	Description
_addr	A URL component of the form myhost.inprise.com:800. If the Address is empty, it is the local host.
_sn	A stringified name of an object.

The following exceptions can be raised by this method.

Exception	Description
InvalidAddress	The specified Address is malformed.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

virtual CORBA::Object_ptr resolve_str(const char* _n);

This operation returns a Name object for the specified stringified name.

Parameter	Description
_n	A stringified name of an object.

The following exceptions can be raised by this method.

Exception	Description
NotFound	The Name, or one of its components, could not be found.
CannotProceed	One of the NameComponent objects in the sequence could not be resolved. The client may still be able to continue the operation from the returned NamingContext.
InvalidName	The specified Name has no name components or the id field of one of its name components is an empty string.

Binding and BindingList

The Binding, BindingList, and BindingIterator interfaces are used to describe the name-object bindings contained in a NamingContext. The Binding struct encapsulates one such pair. The binding_name field represents the Name and the binding_type indicates whether the Name is bound to a VisiBroker ORB object or a NamingContext object.

The BindingList is a sequence of Binding structures contained by a NamingContext object. An example program that uses the BindingList can be found in <install dir>/examples/vbroker/ins/pluggable_adaptor.

Include file

Include the file CosNaming_c.hh when you use these data types and structure.

Code sample

This code sample shows the IDL specification for the Binding structure.

module CosNaming {
enum BindingType {
nobject,
ncontext
};
struct Binding {
Name binding_name;
BindingType binding_type;
};
typedef sequence <Binding> BindingList;
};

BindingIterator

class _VISNMEXPORT BindingIterator : public virtual CORBA_Object

This object allows a client application to walk through the unbounded collection of bindings returned by the NamingContext operation list. An example program that uses the BindingIterator can be found in <install dir>/examples/vbroker/ins/pluggable_adaptor.

Include file

Include the file CosNaming_c.hh when you use this class.

Code sample

This code sample shows the IDL specification for the BindingIterator interface.

module CosNaming {
interface BindingIterator {
boolean next_one(out Binding bl);
boolean next_n(in unsigned long how_many, out BindingList b);
void destroy();
};
};

BindingIterator methods

virtual CORBA::Boolean next_one(Binding_out _b);

This method returns the next Binding from the collection. It returns CORBA::FALSE if the list has been exhausted. Otherwise, it returns CORBA::TRUE.

Parameter	Description
_b	The next Binding object from the list.

virtual CORBA::Boolean next_n(CORBA::ULong _how_many, BindingList_out _bl);

This method returns a BindingList containing the number of requested Binding objects from the list. The number of bindings returned may be less than the requested amount if the list is exhausted. FALSE is returned when the list has been exhausted. Otherwise, TRUE is returned.

Parameter	Description
_how_many	The maximum number of Binding object desired.
_bl	A BindingList containing no more than the requested number of Binding objects.

virtual void destroy();

This method destroys this object and releases the memory associated with the object. Failure to call this method will result in increased memory usage.

NamingContextFactory

class _VISNMEXPORT NamingContextFactory : public virtual CORBA_Object

This interface is provided to instantiate an initial NamingContext. A client may bind to an object of this type and use the create_context method to create an initial context. Once the initial context has been created, the new_context method can be used to create other contexts. An instance of this naming context factory is created when the naming service is started, described in the Naming Service section of the VisiBroker C++ Developer's Guide.

To create an initial NamingContextFactory that automatically creates a single root context, go to “ExtendedNamingContextFactory”.

Include file

Include the file CosNamingExt_c.hh when you use this class.

Code sample

This code sample shows the IDL specification for the NamingContextFactory.

module CosNamingExt {
interface NamingContextFactory {
CosNaming::NamingContextExt create_context();
ClusterManager get_cluster_manager();
void remove_stale_contexts(in string password);
NamingContextList list_all_roots(in string password);
oneway void shutdown();
};
};

Methods

virtual CosNaming::NamingContextExt_ptr create_context();

This method allows a client to create a naming context. Since the specification for naming contexts states that they do not have any notion of a root context, simply instantiating a NamingContextFactory does not create a naming context.

virtual ClusterManager_ptr get_cluster_manager();

This method returns the cluster manager.

virtual NamingContextList* list_all_roots (const char* _password);

This method lists a minimum set of root contexts which allows you to access every context in the namespace.

virtual void remove_stale_contexts (const char* _password);

This method allows the client to remove bindings which relate to a destroyed context.

virtual void shutdown();

This method allows a client to shut the naming service down gracefully. If the service is restarted with the same backing store, the factory is restored to the state it had prior to being shut down.

ExtendedNamingContextFactory

class _VISNMEXPORT ExtendedNamingContextFactory : public virtual CosNamingExt::NamingContextFactory, public virtual CORBA_Object

This interface extends the NamingContextFactory interface and allows the creation of a default root within a factory when the extended naming service is started, described in the Naming Service section of the VisiBroker C++ Developer's Guide.

Include file

Include the file CosNamingExt_c.hh when you use this class.

Code sample

This code sample shows the IDL specification for the ExtendedNamingContextFactory.

module CosNamingExt {
interface ExtendedNamingContextFactory : NamingContextFactory{
CosNaming::NamingContextExt root_context();
};
};

Methods

virtual CosNaming::NamingContextExt_ptr root_context();

This method returns the root naming context that was created automatically when this object was instantiated.