Using the CORBA Name Service

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

CORBA Name Service Reference

This topic includes the following sections:

Note: The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.
Note: Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

 


CORBA Name Service Commands

The CORBA Name Service provides the following commands to manage the server process for the CORBA Name Service, bind and unbind objects to names in the namespace, and display the contents of the namespace:

The following sections describe these commands.

cns

Synopsis

Controls the server process for the CORBA Name Service.

Syntax

cns CLOPT="[-A] [servopts options] --
[-b
bucketcount]
[-c]
[-d]
[-f
filename]
[-M
maxiterators]
[-p [
persiststoragefilename] ]"

Description

The server process for the CORBA Name Service provides a CORBA CosNaming compliant name service. You need to define the server process for the CORBA Name Service and its options in the UBBCONFIG file for your Oracle Tuxedo application as you do any other server process used by your Oracle Tuxedo application. Enter the cns command-line options after the double dash (--) in the CLOPT parameter of the UBBCONFIG file. The command-line options are as follows:

-b bucketcount

Specifies the hash table bucket count used internally by the server process to locate naming contexts in-memory. Each naming context has its own hash table. If your Oracle Tuxedo application uses a small number of bindings in each naming context, use a small bucket count (for example, 4 or 5). If your Oracle Tuxedo application uses a large number of bindings (for example, 1,000) in each naming context, use a larger number such as 50 for the bucket count.

-c

Compresses the persistent storage file when the server process for the CORBA Name Service starts. Over time the persistent storage file can grow in size as naming context and application objects are added and removed from the namespace. Compression reduces the size of the persistent storage file to a minimum. Dangling bindings are removed during compression. Dangling bindings are left in the namespace after the object the binding is associated with is deleted from the namespace. The -p command-line option must be specified when specifying the -c command-line option.

-d

Directs the server process for the CORBA Name Service to delete orphan contexts when the server process starts. An orphan context is a context that is not bound to any other context. It may never have been bound or it may have been bound to a context and the binding was destroyed either explicitly or as a side-effect of a rebind. The -p command-line option must be specified when specifying the -d command-line option.

-f filename

Specifies a file into which the server process for the CORBA Name Service writes the Interoperable Object Reference (IOR) of the root of the namespace.

-M maxiterators

Defines the maximum number of binding iterators that can be outstanding at any one time.
Binding iterators are created when a client application uses the CosNaming::NamingContext::list()method. The client application should use the CosNaming::BindingIterator::destroy()method to delete a binding iterator when the client application is done using the binding iterator. If a client application does not specifically delete binding iterators, the server process for the CORBA Name Service deletes the binding iterators when the number reaches the value specified in the -M command-line option. Once the maximum number of binding iterators is reached, any attempt to create a new binding iterator causes the server process for the CORBA Name Service to destroy a binding iterator currently in use by the client application. Binding iterators are deleted using a least-recently-used algorithm. The default value is 20. A value of 0 indicates that there is no maximum number of binding iterators (meaning binding interators are never destroyed by the server process for the CORBA Name Service and the associated memory is not released). If a value of 0 is specified, the client application must explicitly use the CosNaming::BindingIterator::destroy() method to delete outstanding binding iterators.

-p [persistentstoragefilename]

Directs the server process for the CORBA Name Service to save a copy of the current namespace to persistent storage using the specified file. If a filename is not specified, the value of the CNS_PERSIST_FILE environment variable is used. If the CNS_PERSIST_FILE environment variable is not set, the following files are used:
Windows %APPDIR%\cnspersist.dat UNIX $APPDIR/cnspersist.dat The persistent storage file is read when the server process for the CORBA Name Service starts. The persistent storage file is added to as changes are made to the namespace. If you want to create a new namespace, the existing persistent storage file must be deleted or a new one must be created on the server process for the CORBA Name Service.

cnsbind

Synopsis

Binds application objects and naming context objects into the namespace.

Note: The cnsbind command interacts with the CosNaming interfaces. The server process for the CORBA Name Service must be running to use this command.

Syntax

cnsbind
[-C]
[-f
root_context_filename]
[-h]
[-N]
[-o
ior_filename]
[-r]
[-T
TObjAddr]
bind_name

Description

The cnsbind command binds new application and naming context objects into the namespace using the CORBA CosNaming interfaces. This command facilitates the creation of a federated namespace. If an exception is returned when the cnsbind command is invoked, the command exits and an appropriate message is displayed.

The command-line options for the cnsbind command are as follows:

-C

Specifies that the cnsbind command creates a context using the bind_name for the name and the ior_filename specified for the -o command-line option. The -C command-line option is used to federate a naming context object from one namespace into the specified namespace.

-f root_context_filename

Specifies the file containing the IOR of the server process for the CORBA Name Service with which the command interacts to modify the contents of the namespace. If this command-line option is not specified, the command uses the Tobj_Bootstrap::resolve_initial_references() method with the NameService environmental object to locate the server process for the CORBA Name Service in the specified Oracle Tuxedo domain. The host and port in the IOR must match the value of TOBJADDR. This command-line option overrides the setting for the TOBJADDR environment variable. If the command-line option is not specified, the TOBJADDR environment variable is used.

-h

Prints the command syntax.

-N

Creates a new context and binds the new context into the namespace using the specified name. The -o command-line option is not needed with the -N command-line option because the cnsbind command is creating a new context. If the -o command-line option is used with the -N command-line option, the information from the -o command-line option is ignored.

-o ior_filename

Specifies a file that contains the IOR of the object to be bound into the namespace specified via the -f command-line option. If the -C command-line option is specified, an object of type ncontext is created otherwise a object of type nobject is created.

-r

Creates a binding for an application or naming context object even if the name already has a binding. The default behavior of the cnsbind command without the -r command-line option is to raise the AlreadyBound exception in the case where a binding for the specified object already exists. If an AlreadyBound or any other exception is returned when the cnsbind command is invoked, the command exits and an “Error, already bound” message is displayed.

-T TObjAddr

Specifies the host and port for an Oracle Tuxedo domain. Before connecting to a server process for the CORBA Name Service, the cnsbind command must log into the Oracle Tuxedo domain in which the server process is running. This command-line option overrides the setting for the TOBJADDR environment variable. If the command-line option is not specified, the value of the TOBJADDR environment variable is used. If the command-line option is not specified and TOBJADDR is not set, the program will run as a native client and load the TGIOP protocol.
The valid format for the TObjAddr specification is //hostname:port_number.

bind_name

Specifies the name to be bound to the application object or name context object added to the namespace relative to either the root naming context retrieved from the Tobj_Bootstrap::resolve_initial_references method, or the naming context identified by the stringified IOR obtained from the -f command-line option. The bind_name string should conform to the name string form specified in the Object Management Group (OMG) Interoperable Name Service (INS) specification.

Examples

The following example illustrates binding an application object:

cnsbind -o ./app_obj_ior.txt MyContext/AppObject1

The following example illustrates binding a naming context object:

cnsbind -N MyContext/CtxObject1

The following example illustrates binding a federation point to another namespace:

cnsbind -C -o ./remote_ior.txt MyContext/RemoteNSCtx1

cnsls

Synopsis

Displays the contents of the namespace.

Note: The cnsls command interacts with the CosNaming interfaces. The server process for the CORBA Name Service must be running to use this command.

Syntax

cnsls
[-f
root_context_filename]
[-h]
[-s]
[-R]
[-T
TobjAddr]
[
resolve_name]

Description

The cnsls command displays the contents of the namespace using the CORBA CosNaming interfaces. If non-printing characters are used as part of a NameComponent data structure, the behavior of the cnsls command is undefined. If an exception is returned when the cnsls command is invoked, the command exits and an appropriate message is displayed.

The command-line options for the cnsls command are as follows:

-f root_context_filename

Specifies the file containing the IOR of the server process for the CORBA Name Service with which the command interacts to modify the contents of the namespace. If this command-line option is not specified, the command uses the Tobj_Bootstrap::resolve_initial_references() method with the NameService environmental object to locate the server process for the CORBA Name Service in the specified Oracle Tuxedo domain. The host and port in the IOR must match the value of TObjAddr. This command-line option overrides the setting for the TOBJADDR environment variable. If the command-line option is not specified, the value of the TOBJADDR environment variable is used.

-h

Prints the command syntax.

-s

Displays the stringified IOR for the namespace name specified in resolve_name command-line option.

-R

Recursively displays namespace bindings beginning at resolve_name. This command-line option may cause the cnsls command to cross federation boundaries with no indication when such a boundary is cross. Also, if cycles exist in the namespace information, this command-line option can cause the cnsls command to enter a loop.

-T TObjAddr

Specifies the host and port for an Oracle Tuxedo domain. Before connecting to a server process for the CORBA Name Service, the cnsls command must log into the Oracle Tuxedo domain in which the server process is running. This command-line option overrides the setting for the TOBJADDR environment variable. If the command-line option is not specified, the TOBJADDR environment variable is used.

resolve_name

Specifies the name to resolve in the name service relative to either the root naming context retrieved via the Tobj_Bootstrap::resolve_initial_references() method or the naming context identified by the stringified IOR obtained from the -f command-line option. The resolve_name string should conform to the name string form specified in the OMG INS specification. The backslash (\) character is used to delimit name components and the period (.) character separates the id and kind fields.
If this command-line option is not specified, the root context is resolved.

Example

cnsls -R MyContext.kind/AnotherContext
[context] MyContext.kind/AnotherContext
[object] Obj1
[object] Obj2
[context] Ctx1
[object] AnotherObject

cnsunbind

Synopsis

Removes bindings from the namespace.

Syntax

cnsunbind
[-D]
[-f
root_context_filename]
[-h]
[-T
TObjAddr]
bind_name

Description

The cnsubind command removes bindings from the namespace. If an exception is returned when the cnsunbind command is invoked, the command exits and an appropriate message is displayed.

The cnsunbind command-line options are as follows:

-D

Destroys the naming context bound to the bind_name after removing the binding. Specifying the -D command-line option when deleting a context prevents the context from being orphaned if it is not part of another binding. This command-line option should be used with care because it can cause dangling bindings (for example, if the binding was bound to multiple naming context objects at the same time).

-f root_context_filename

Specifies the file containing the IOR of the server process for the CORBA Name Service with which the command interacts to modify the contents of the namespace. If this command-line option is not specified, the command uses the Tobj_Bootstrap::resolve_initial_references() method with the NameService environmental object to locate the server process for the specified Oracle Tuxedo domain.

-h

Prints the command syntax.

-T TObjAddr

Specifies the host and port for an Oracle Tuxedo domain. Before connecting to a server process for the CORBA Name Service, the cnsbind command must log into the Oracle Tuxedo domain in which the server process is running. This command-line option overrides the setting for the TOBJADDR environment variable. If the command-line option is not specified, the TOBJADDR environment variable is used.

bind_name

Specifies the name of the binding to be removed from the namespace relative to either the root naming context retrieved via the Tobj_Bootstrap::resolve_initial_references() method or the naming context identified by the stringified IOR obtained from the -f command-line option. The bind_name string should conform to the name string form specified in the OMG INS specification.

Examples

The following example illustrates removing a binding from the namespace:

cnsunbind MyContext/CtxObject1

The following example illustrates removing a binding from the namespace and destroying the object to which it was bound:

cnsunbind -D MyContext/CtxObject1

 


Capabilities and Limitations of the CORBA Name Service

The CORBA Name Service has the following capabilities and limitations:

 


Getting the Initial Reference to the NameService Environmental Object

A NameService environmental object is available for connecting to the root of the namespace. When using the NameService environmental object, the Object Request Broker (ORB) locates the root of the namespace. Use the Bootstrap object or the CORBA Interoperable Naming Service (INS) bootstrapping mechanism to get an initial reference to the NameService environmental object. Use the Oracle proprietary mechanism if you are using the Oracle client ORB. Use the CORBA INS mechanism is you are using a client ORB from another vendor.

For more information on connecting to the namespace, see Step 3: Connect to the Oracle Tuxedo Namespace. For more information about bootstrapping the Oracle Tuxedo domain see Chapter 4, “CORBA Bootstrapping Programming Reference,” in the CORBA Programming Reference in the Oracle Tuxedo online documentation.

 


The CosNaming Data Structures Used by the CORBA Name Service

The CORBA Name Service uses the following CosNaming data structures:

 


The NamingContext Object

The NamingContext object is used to contain and manipulate a list of names that are bound to Object Request Broker (ORB) objects or to other NamingContext objects. Oracle Tuxedo CORBA client applications use this interface to resolve or list all the names within that context. Oracle Tuxedo CORBA server applications use this object to bind names to application objects or naming context objects. Listing 2-1 shows the OMG IDL for the NamingContext object.

Listing 2-1 OMG IDL for the NamingContext Object
module CosNaming {
  interface NamingContext {
    void bind(in Name, in Object obj)
       raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
    void rebind(in Name, 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);
    }
}

CosNaming::NamingContext::bind()

Synopsis

Attempts to bind the specified object to the specified name by resolving the context associated with the first NameComponent data structure and then binding the object to the new context.

C++ Mapping

void bind(in Name n, in Object obj); 

Parameters

n

A Name data structure, initialized with the desired name of the object.

obj

The object to bind to the supplied name.

Exceptions

AlreadyBound

The Name on a bind() or a bind_context() method has already been bound to another object within the naming context.

InvalidName

The specified Name has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The Name or one of its components, could not be found.

Description

Naming contexts bound with bind do not participate in name resolution when compound names are passed to be resolved.

Return Value

None.

CosNaming::NamingContext::bind_context()

Synopsis

This method is similar to the bind() method, except that the supplied Name is associated with a NamingContext object.

C++ Mapping

void bind_context(in Name n, in NamingContext nc); 

Parameters

n

A Name data structure initialized with the desired name for the naming context. The first NameComponent data structure in the sequence must resolve to a naming context.

nc

The NamingContext object to be bound to the supplied name.

Exceptions

AlreadyBound

The Name on a bind() or a bind_context() method has already been bound to another object within the naming context.

InvalidName

The specified Name has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The Name or one of its components, could not be found.

BAD_PARAM

Indicates the call attempted to bind a NULL context.

Description

Naming contexts bound with bind_context() participate in name resolution when compound names are passed to be resolved.

Return Value

None.

CosNaming::NamingContext::bind_new_context()

Synopsis

Creates a new context and binds it to the specified Name within this context.

C++ Mapping

NamingContext bind_new_context(in Name n); 

Parameter

n

A Name data structure, initialized with the desired name for the newly created NamingContext object.

Exceptions

AlreadyBound

The Name on a bind() or a bind_context() method has already been bound to another object within the naming context.

InvalidName

The specified Name has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The Name or one of its components could not be found.

Description

This method combines the CosNaming::NamingContext::new_context() and CosNaming::NamingContext::bind_context() methods into a single method.

Return Value

Returns a reference to a new NamingContext object.

CosNaming::NamingContext::destroy()

Synopsis

Deletes a NamingContext object. Any subsequent attempt to invoke methods on the NamingContext object raises a CORBA::NO_IMPLEMENT exception.

C++ Mapping

void destroy(); 

Parameter

None.

Exceptions

NotEmpty

If the NamingContext object contains bindings, the method raises NotEmpty.

Description

Before using this method, all name objects that have been bound to the NamingContext object should be unbound using the
CosNaming::NamingContext::unbind() method.

Return Value

None.

CosNaming::NamingContext::list()

Synopsis

Returns all of the bindings contained by this naming context.

C++ Mapping

void list(in unsigned_long how_many, 
    out BindingList
bl,
    out BindingIterator
bi);

Parameters

how_many

The maximum number of bindings to be returned in the list.

bl

A list of returned bindings where each element is a binding containing a Name representing a single NameComponent object. Each Name is a simple name, that is, a name sequence of length 1. The number of bindings in the list does not exceed the value of how_many.

bi

A reference to a BindingIterator object for use in traversing the rest of the bindings.

Exceptions

InvalidName

The specified Name has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The Name or one of its components could not be found.

Description

This method returns a sequence of name bindings. If more name bindings exist than can fit in the bl list, a BindingIterator object is returned. The BindingIterator object can be used to get the next set of bindings. The BindingList (C++) object can return less than the requested number of bindings if it is at the end of the list. If bi returns a NULL reference, then bl contains all of the bindings.

Return Value

None.

CosNaming::NamingContext::new_context()

Synopsis

Creates a new naming context. The newly created context is initially not bound to any Name.

C++ Mapping

NamingContext new_context(); 

Parameter

None.

Exceptions

None.

Description

Use the CosNaming::NamingContext::bind_context() method to bind the new naming context to a Name.

Return Value

Returns a reference to a new naming context.

CosNaming::NamingContext::rebind()

Synopsis

This method is similar to the bind() method. The difference is that the rebind method does not raise the AlreadyBound exception. If the specified Name has already been bound to another object, that binding is replaced by the new binding.

C++ Mapping

void rebind(in Name n, in Object obj); 

Parameters

n

A Name data structure, initialized with the desired name for the object.

obj

The object to be named.

Exceptions

InvalidName

The specified Name data structure has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The Name or one of its components, could not be found. If this exception is raised because the binding already exists or the binding is of the wrong type, the rest_of_name member of the exception has a length of 1.

Description

Naming contexts bound with the rebind()method do not participate in name resolution when compound names are passed to be resolved.

Return Value

None.

CosNaming::NamingContext::rebind_context()

Synopsis

This method is similar to the bind_context() method. The difference is that the rebind_context method does not raise the AlreadyBound exception. If the specified Name has already been bound to another object, that binding is replaced by the new binding.

C++ Mapping

void rebind_context(in Name n, in NamingContext nc); 

Parameters

n

A Name data structure, initialized with the desired name for the object.

nc

The NamingContext object to be rebound.

Exceptions

InvalidName

The specified Name data structure has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The component of a name does not identify a binding or the type of binding is incorrect for the operation being performed. If this exception is raised because a binding already exists or it is of the wrong type, the rest_of_name member of the exception has a length of 1.

Description

Naming contexts bound with the rebind_context method do not participate in name resolution when compound names are passed to be resolved.

Return Value

None.

CosNaming::NamingContext::resolve()

Synopsis

Attempts to resolve the specified Name.

C++ Mapping

Object resolve(in Name n); 

Parameters

n

A Name data structure, initialized with the desired name for the object.

Exceptions

InvalidName

The specified Name data structure has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The component of a name does not identify a binding or the type of binding is incorrect for the operation being performed.

Description

The specified Name must exactly match the name used to bind the object. The CORBA Name Service does not return the type of the object. Client applications are responsible for narrowing the object to the appropriate type.

Return Value

Returns the object reference for the specified Name.

CosNaming::NamingContext::unbind()

Synopsis

Performs the inverse operation of the bind() method, removing the binding associated with the specified Name.

C++ Mapping

void unbind(in Name n); 

Parameters

n

A Name data structure, initialized with the desired name for the object.

Exceptions

InvalidName

The specified Name data structure has zero name components or one of the first name components did not resolve to a naming context.

NotFound

The component of a name does not identify a binding or the type of binding is incorrect for the operation being performed.

Description

This method removes the binding between a name and an object. It does not delete the object. Use the CosNaming::NamingContext::unbind() method and then the CosNaming::NamingContext::destroy() method to delete the object.

Return Value

None.

 


The NamingContextExt Object

The NamingContextExt object provides methods to use URLs and stringified names in the CORBA Name Service. The NamingContextExt object is derived from the NamingContext object. Note that the root of the CORBA Name Service is a NamingContextExt object (which means the root is also a NamingContext object). No special operation is needed to obtain a reference to a NamingContextExt object. Listing 2-2 shows the OMG IDL for the NamingContextExt object.

Listing 2-2 OMG IDL for the NamingContextExt Object
module CosNaming {
       interface NamingContextExt : NamingContext {
              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,
                            AlreadyBound);
       }
}

CosNaming::NamingContextExt::resolve_str()

Synopsis

Takes a stringified name, converts it to a Name, and resolves it.

Syntax

object resolve_str(in StringName n);

Parameter

n

The stringified name to be resolved.

Exceptions

InvalidName

The name is invalid. A name of length zero is invalid.

NotFound

The component of the name does not identify a binding or the type of the binding is incorrect for the operation being performed.

Description

This is a convenience method that performs a resolve in the same manner as the
CosNaming:NamingContext::resolve() method. The method accepts a stringified name as an argument instead of a Name object. The method returns errors if the stringified name is invalid or if the method cannot bind it.

Return Value

A reference to the bound name.

CosNaming::NamingContextExt::to_name()

Synopsis

Takes a stringified name and returns a Name object.

Syntax

Name to_name(in StringName sn);

Parameter

sn

The stringified name to be resolved to a Name object.

Exceptions

InvalidName

The name is invalid. A name of length zero is invalid.

Description

This method accepts a stringified name and returns a Name object. The method returns errors if the name is invalid.

Return Value

Returns a Name object.

CosNaming::NamingContextExt::to_string()

Synopsis

Accepts a Name object and returns a stringified name.

Syntax

StringName to_string(in Name n);

Parameter

n

The Name object to be converted to stringified name

Exceptions

InvalidName

The name is invalid. A name of length zero is invalid.

Description

This method accepts a Name object and returns a stringified name. It returns errors if the name is invalid.

Return Value

Returns a stringified name.

CosNaming::NamingContextExt::to_URL()

Synopsis

Combines a URL and a stringified name and returns a URL string.

Syntax

CosNaming::NamingContextExt::to_URL()

URLString to_URL(in Address addr, in StringName sn);

Parameter

addr

A URL. If this parameter is not defined, the local host name is used with the IIOP protocol.

sn

The stringified name to be combined with the URL.

Exceptions

InvalidAddress

The URL is invalid.

InvalidName

The name is invalid. A name of length zero is invalid.

Return Value

Returns a URL string that combines the URL and the stringified name.

 


The BindingIterator Object

The BindingIterator object allows a client application to walk through the unbounded collection of bindings returned by the list method of a
NamingContext object. Using the BindingIterator object, a client application can control the number of bindings obtained with each call. If a naming context is modified between calls to the methods of a BindingIterator object, the behavior of further calls to the next_one() method or the next_n() method is implementation specific.

If a client application creates BindingIterator objects but never calls the destroy method, the client application can run out of resources. The CORBA Name Service is free to destroy binding iterators at any time and without warning to the client application. Client applications should be written to expect the OBJECT_NOT_EXIST exception from calls to a BindingIterator object and to handle this exception gracefully.

Listing 2-3 shows the OMG IDL for the BindingIterator object.

Listing 2-3 OMG IDL for BindingIterator Object
module CosNaming {
       interface BindingIterator {
              boolean next_one(out Binding b);
              boolean next_n(in unsigned long how_many,
                             out BindingList b);
              void destroy();
       };
}

CosNaming::BindingIterator::destroy()

Synopsis

Destroys the BindingIterator object and releases the memory associated with the object. Failure to call this method results in increased memory usage.

C++ Mapping

void destroy();

Parameter

None.

Exceptions

None.

Description

If a client application invokes any operation on a BindingIterator object after calling the destroy method, the operation raises an OBJECT_NOT_EXIST exception.

Return Value

None.

CosNaming::BindingIterator::next_n()

Synopsis

Returns a BindingList data structure containing the number of requested bindings from the list. The number of bindings returned may be less than the requested amount if the list is exhausted.

C++ Mapping

boolean next_n(in unsigned_long how_many, out BindingList bl); 

Parameter

how_many

The maximum number of bindings to return.

bl

A BindingList data structure containing no more than the requested number of bindings.

Exceptions

BAD_PARAM

Raised if the how_many parameter has a value of zero.

Return Value

CORBA::FALSE is returned when the list has been exhausted. Otherwise, CORBA::TRUE is returned.

CosNaming::BindingIterator::next_one()

Synopsis

Returns the next Binding object in the list.

C++ Mapping

boolean next_one(out Binding b); 

Parameter

b

The next Binding object from the list.

Exceptions

None.

Return Value

CORBA::FALSE is returned when the list has been exhausted. Otherwise, CORBA::TRUE is returned.

 


Exceptions Raised by the CORBA Name Service

This section describes the exceptions raised by the CORBA Name Service.

AlreadyBound

Syntax

exception AlreadyBound{}; 

Parameter

None.

Description

This exception is raised when an object is already bound to the supplied name. Only one object can be bound to a name in a context.

CannotProceed

Syntax

exception CannotProceed{};

Parameters

NamingContext cxt

The context that the operation may be able to retry from.

Name rest_of_name

The remainder of the non working name.

Description

This exception is raised when an unexpected exception is encountered and the method cannot proceed in a meaningful way.

InvalidAddress

Syntax

exception InvalidAddress{};

Parameter

None.

Description

This exception is raised if a URL is invalid.

InvalidName

Syntax

exception InvalidName{};

Parameter

None.

Description

This exception is raised if a Name is invalid. A name length of zero is invalid.

NotEmpty

Syntax

exception NotEmpty{};

Parameter

None.

Description

This exception is raised when the destroy()method is used on a NamingContext object that contains bindings. A NamingContext object must be empty before it is destroyed.

NotFound

Syntax

exception NotFound{NotFoundReason why; Name rest_of_name;};

Parameters

why

The context that the operation may be able to retry from.

rest_of_name

The remainder of the non-working name.

Description

This exception is raised when a component of the name does not identify a binding, or if the type of binding is incorrect for the operation being performed. The why parameter explains the reason for the error. The rest_of_name parameter identifies the cause of the error. The following causes can appear:


  Back to Top       Previous  Next