![BEA BEA Tuxedo Release [Release Number]](../images/top.gif)
|
|
|
|
|
|
CORBA Name Service Reference
This topic includes the following sections:
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 BEA Tuxedo application as you do any other server process used by your BEA 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:
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:
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:
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:
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 BEA proprietary mechanism if you are using the BEA 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 BEA Tuxedo Namespace" in Chapter 4. For more information about bootstrapping the BEA Tuxedo domain see Chapter 4, "CORBA Bootstrapping Programming Reference," in the CORBA Programming Reference in the BEA 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. BEA Tuxedo CORBA client applications use this interface to resolve or list all the names within that context. BEA 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);
Java Mapping
void bind (NameComponent [] n, Object obj);
Parameters
Exceptions
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);
Java Mapping
void bind_context (NameComponent [] n, NamingContext nc);
Parameters
Exceptions
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);
Java Mapping
bind_new_context (NameComponent [] n);
Parameter
Exceptions
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();
Java Mapping
void destroy();
Parameter
Exceptions
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);
Java Mapping
void list(int how_many,
BindingListHolder bl,
BindingIteratorHolder bi);
Parameters
Exceptions
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++) or BindingListHolder (Java) 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();
Java Mapping
NamingContext new_context();
Parameter
Exceptions
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);
Java Mapping
void rebind(NameComponent [] n, Object obj);
Parameters
Exceptions
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);
Java Mapping
void rebind_context(NameComponent [] n, NamingContext nc);
Parameters
Exceptions
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);
Java Mapping
Object resolve (NameComponent n);
Parameters
Exceptions
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);
Java Mapping
void unbind (NameComponent [] n);
Parameters
Exceptions
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
Exceptions
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
Exceptions
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
Exceptions
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
Exceptions
The URL is invalid.
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();
Java Mapping
void destroy();
Parameter
Exceptions
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);
Java Mapping
boolean next_n(int how_many, BindingListHolder bl);
Parameter
Exceptions
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);
Java Mapping
boolean next_one(BindingHolder b);
Parameter
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
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
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:
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|