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. |
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.
Controls the server process for the CORBA Name Service.
cns CLOPT="[-A] [servopts
options
] --
[-b bucketcount
]
[-c]
[-d]
[-f filename
]
[-M maxiterators
]
[-p [persiststoragefilename
] ]"
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
-c
-p
command-line option must be specified when specifying the -c
command-line option.
-d
-p
command-line option must be specified when specifying the -d
command-line option.
-f
filename
-M
maxiterators
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
]
CNS_PERSIST_FILE
environment variable is used. If the CNS_PERSIST_FILE
environment variable is not set, the following files are used:
%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.
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. |
cnsbind
[-C]
[-f root_context_filename
]
[-h]
[-N]
[-o ior_filename
]
[-r]
[-T TObjAddr
]
bind_name
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
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
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
-N
-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
-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
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
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.
bind_name
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.
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
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. |
cnsls
[-f root_context_filename
]
[-h]
[-s]
[-R]
[-T TobjAddr
]
[resolve_name
]
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
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
-s
-R
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
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
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.
cnsls -R MyContext.kind/AnotherContext
[context] MyContext.kind/AnotherContext
[object] Obj1
[object] Obj2
[context] Ctx1
[object] AnotherObject
Removes bindings from the namespace.
cnsunbind
[-D]
[-f root_context_filename
]
[-h]
[-T TObjAddr
]
bind_name
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
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
Tobj_Bootstrap::resolve_initial_references()
method with the NameService environmental object to locate the server process for the specified Oracle Tuxedo domain.
-h
T
TObjAddr
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
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.
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
The CORBA Name Service has the following capabilities and limitations:
NULL
character must only be used to terminate the id
and kind
strings (empty strings are considered valid).CannotProceed
exception.
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 CORBA Name Service uses the following CosNaming data structures:
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.
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);
}
}
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.
void bind(in Name
n
, in Object
obj
);
n
obj
AlreadyBound
Name
on a bind()
or a bind_context()
method has already been bound to another object within the naming context.
InvalidName
Name
has zero name components or one of the first name components did not resolve to a naming context.
NotFound
Naming contexts bound with bind
do not participate in name resolution when compound names are passed to be resolved.
This method is similar to the bind()
method, except that the supplied Name
is associated with a NamingContext
object.
void bind_context(in Name
n
, in NamingContext
nc
);
n
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
AlreadyBound
Name
on a bind()
or a bind_context()
method has already been bound to another object within the naming context.
InvalidName
Name
has zero name components or one of the first name components did not resolve to a naming context.
NotFound
BAD_PARAM
Naming contexts bound with bind_context()
participate in name resolution when compound names are passed to be resolved.
Creates a new context and binds it to the specified Name
within this context.
NamingContext bind_new_context(in Name n);
n
Name
data structure, initialized with the desired name for the newly created NamingContext
object.
AlreadyBound
Name
on a bind()
or a bind_context()
method has already been bound to another object within the naming context.
InvalidName
Name
has zero name components or one of the first name components did not resolve to a naming context.
NotFound
This method combines the CosNaming::NamingContext::new_context()
and CosNaming::NamingContext::bind_context()
methods into a single method.
Returns a reference to a new NamingContext
object.
Deletes a NamingContext
object. Any subsequent attempt to invoke methods on the NamingContext
object raises a CORBA::NO_IMPLEMENT
exception.
void destroy();
NotEmpty
Before using this method, all name objects that have been bound to the NamingContext
object should be unbound using theCosNaming::NamingContext::unbind()
method.
Returns all of the bindings contained by this naming context.
void list(in unsigned_long
how_many
,
out BindingListbl
,
out BindingIteratorbi
);
how_many
bl
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
InvalidName
Name
has zero name components or one of the first name components did not resolve to a naming context.
NotFound
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.
Creates a new naming context. The newly created context is initially not bound to any Name
.
NamingContext new_context();
Use the CosNaming::NamingContext::bind_context()
method to bind the new naming context to a Name.
Returns a reference to a new naming context.
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.
void rebind(in Namen
, in Objectobj
);
n
obj
InvalidName
Name
data structure has zero name components or one of the first name components did not resolve to a naming context.
NotFound
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.
Naming contexts bound with the rebind()
method do not participate in name resolution when compound names are passed to be resolved.
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.
void rebind_context(in Namen
, in NamingContextnc
);
n
nc
InvalidName
Name
data structure has zero name components or one of the first name components did not resolve to a naming context.
NotFound
rest_of_name
member of the exception has a length of 1.
Naming contexts bound with the rebind_context
method do not participate in name resolution when compound names are passed to be resolved.
Attempts to resolve the specified Name
.
Object resolve(in Name n
);
n
InvalidName
Name
data structure has zero name components or one of the first name components did not resolve to a naming context.
NotFound
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.
Returns the object reference for the specified Name
.
Performs the inverse operation of the bind()
method, removing the binding associated with the specified Name
.
void unbind(in Name
n
);
n
InvalidName
Name
data structure has zero name components or one of the first name components did not resolve to a naming context.
NotFound
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.
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.
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);
}
}
Takes a stringified name, converts it to a Name
, and resolves it.
object resolve_str(in StringName
n
);
n
InvalidName
NotFound
This is a convenience method that performs a resolve in the same manner as theCosNaming: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.
A reference to the bound name.
Takes a stringified name and returns a Name
object.
Name to_name(in StringName
sn
);
sn
InvalidName
This method accepts a stringified name and returns a Name
object. The method returns errors if the name is invalid.
Accepts a Name
object and returns a stringified name.
StringName to_string(in Name n
);
n
InvalidName
This method accepts a Name
object and returns a stringified name. It returns errors if the name is invalid.
Combines a URL and a stringified name and returns a URL string.
CosNaming::NamingContextExt::to_URL(
)
URLString to_URL(in Addressaddr
, in StringNamesn
);
addr
sn
InvalidAddress
InvalidName
Returns a URL string that combines the URL and the stringified name.
The BindingIterator
object allows a client application to walk through the unbounded collection of bindings returned by the list
method of aNamingContext
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.
module CosNaming {
interface BindingIterator {
boolean next_one(out Binding b);
boolean next_n(in unsigned long how_many,
out BindingList b);
void destroy();
};
}
Destroys the BindingIterator
object and releases the memory associated with the object. Failure to call this method results in increased memory usage.
void destroy();
If a client application invokes any operation on a BindingIterator
object after calling the destroy
method, the operation raises an OBJECT_NOT_EXIST
exception.
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.
boolean next_n(in unsigned_longhow_many
, out BindingListbl
);
how_many
bl
BAD_PARAM
CORBA::FALSE
is returned when the list has been exhausted. Otherwise, CORBA::TRUE
is returned.
Returns the next Binding
object in the list.
boolean next_one(out Binding b
);
b
CORBA::FALSE
is returned when the list has been exhausted. Otherwise, CORBA::TRUE
is returned.
This section describes the exceptions raised by the CORBA Name Service.
exception AlreadyBound{};
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.
exception CannotProceed{};
NamingContext
cxt
Name
rest_of_name
This exception is raised when an unexpected exception is encountered and the method cannot proceed in a meaningful way.
exception InvalidAddress{};
This exception is raised if a URL is invalid.
exception InvalidName{};
Name
is invalid. A name length of zero is invalid.
exception NotEmpty{};
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.
exception NotFound{NotFoundReason why; Name rest_of_name;};
why
rest_of_name
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:
missing_node
—the first name component in the rest_of_name
parameter is a binding that is not bound under that name within its parent context.not_context
—the first name component in the rest_of_name
parameter is a binding with a type of nobject
when the type of ncontext
was required.not_object
—the first name component in the rest_of_name
parameter is a binding with a type of ncontext
when the type of nobject
was required.