Please send feedback to jndi@java.sun.com
Table of Contents
The Common Object Services (COS) Name Server is the name server for
storing Common Object Request Broker Architecture (CORBA) object
references. It can be accessed from CORBA applications by using the COS
Naming package (org.omg.CORBA.CosNaming).
The JNDI/COS naming service provider implements the
javax.naming.Context interface on top of the COS Naming package
in order to allow applications to use JNDI to access the COS Name Server.
JNDI can also be used to access other naming and directory services,
in addition to the COS Name Server, thereby offering the CORBA
application one interface for accessing different naming and directory
services.
This document describes the features of the COS naming service provider
and contains details of how JNDI is mapped to the COS naming package.
The COS naming service provider for JNDI uses
JavaTM IDL, the Java programming language mapping
to the industry standard Object Management Group Interface
Definition Language (OMG IDL).
In particular, it uses the
COS Naming Service.
The complete specification for COS Naming can be obtained from
OMG.
The syntax of names conforms to the
Interoperable
Naming Service (INS) specification (99-12-03),
with backward compatibility support for the previous version of INS,
OMG TC Document orbos/98-10-11.
This is described in Names and URLs.
The following JNDI environment properties are relevant for the
COS naming service provider. See the
JNDI documentation
for a
description of how properties are initialized using the environment
properties, system properties, applet parameters, and resource files.
For example:
This property must be set if you are using the
COS naming service as the initial context. The only exception is
if you supply only URLs to the initial context, in which case,
you don't need to specify this property. See
Names and URLs for details.
If this property is not specified, then the ORB is initialized using the
java.naming.corba.orb property, the
java.naming.applet property, or
other ORB initialization properties.
The root naming context is obtained by invoking
If the URL scheme is one of "IOR", "corbaname", or "corbaloc", as specified
in the INS
specification (99-12-03), then the root naming context is
that named by the URL.
The ORB is initialized using the
java.naming.corba.orb property, the
java.naming.applet property, or
other ORB initialization properties.
If the URL scheme is either "iiop" or "iiopname", then the host and
port fields of the URL are used to initialize the ORB. An
"iiopname" URL must conform to the now obsolete
INS
specification (98-10-11).
It has the form:
The "iiop" URL scheme is supported for backward compatibility
with an older version
of the INS specification. It has the form:
For both "iiop" and "iiopname" URLs, if <host> is not specified,
then it defaults to "localhost" for an application and the applet's host for
an applet. If <port> is not specified, then it defaults to 9999
for "iiopname",
and 900 for "iiop". The root naming context is obtained by invoking the
following method on the ORB:
If <cosnaming_name> is nonempty, then
the root naming context is the
naming context named by cosnaming_name.
If the URL scheme is not one of "iiop", "iiopname", "IOR", "corbaname",
or "corbaloc", then the URL must name a location that contains the stringified
IOR of the root naming context.
For example, if the property contains "file:/nsdir/ior", then the file
/nsdir/ior must contain a stringified IOR. The URL scheme can be any
for which there is a corresponding URL protocol handler (
java.net.URLStreamHandler
When the property specifies a stringified IOR or the location of one,
the root naming context is that named by the the stringified IOR.
The ORB is initialized using the
java.naming.corba.orb property, the
java.naming.applet property, or
other ORB initialization properties.
In an application you can set this property as follows:
Introduction
Conformance
Environment Properties
java.naming.factory.initial
This property is used to select the COS naming service provider; it's
not actually used by the provider itself. It specifies the class name
of the initial context factory for the provider.
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.cosnaming.CNCtxFactory");
java.naming.provider.url
This property is used to configure the root naming context
and/or the Object Request Broker (ORB).
Its value is the string representation of a URL.
). See the
java.net.URL class for details.
The stringified IOR is read from the data stream corresponding to the
URL by using a character encoding of ISO Latin-1. The stringified IOR
is the first line in the stream that contains the prefix "IOR:". For
example, if the URL scheme is "http", then the headers in the stream are
skipped and the first line that contains the prefix "IOR:" is returned as
the IOR.
orb.resolve_initial_references("NameService");
iiopname://[<addr_list>][/<cosnaming_name>]
iiop://[<host>[:<port>]][/<cosnaming_name>]
orb.resolve_initial_references("NameService");
java.naming.corba.orb
This property specifies the ORB that the program is using.
When the JNDI COS naming service provider needs to use an ORB, for
example, to look up the "NameService" initial reference or to
turn a stringified IOR into an object reference, it will use
this ORB.
In an applet, you can set it as follows:
ORB orb = ORB.init(args, null);
Hashtable env = new Hashtable(5, 0.75f);
env.put("java.naming.corba.orb", orb);
...
If this property is not set, then the
java.naming.provider.url property, the
java.naming.applet property, or
the ORB initialization properties
are used to initialize the ORB.
public class MyApplet extends Applet {
public someInitMethod() {
ORB orb = ORB.init(this, null);
Hashtable env = new Hashtable(5, 0.75f);
env.put("java.naming.corba.orb", orb);
...
}
...
}
java.naming.applet
This property specifies the applet that the program is using. It is used to initialize the ORB to be used by the COS naming service provider. Its parameters are used for setting JNDI-related properties; see the JNDI documentation for details.public class MyApplet extends Applet { public someInitMethod() { Hashtable env = new Hashtable(5, 0.75f); env.put("java.naming.applet", this); ... } ... }
java.naming.factory.state
A colon-separated list of the fully qualified class names of state factory classes used to get an object's state for storing given the object itself. You can use this mechanism to transform an object into forms that can be stored into a COS name server. The COS name server supports storing CORBA objects.A state factory that transforms a java.rmi.Remote into a CORBA object is supplied by default. This factory is useful for applications that use RMI-IIOP. You can supply other factories to affect the transformation of other objects into CORBA objects for storing. See javax.naming.spi.NamingManager.getStateToBind() for details.
java.naming.factory.object
A colon-separated list of the fully qualified class names of object factory classes for transforming a CORBA object. You can use this mechanism to transform an object into forms expected by the application. For example, a specialized object factory could do the appropriate narrowing to return an object of the expected type. See javax.naming.spi.NamingManager.getObjectInstance() for details.
java.naming.batchsize
Specifies the batch size to use in CosNaming::BindingIterator.next_n when getting the results of a list()/listBindings(). The default is "100."ORB initialization propertiesFor example, the following sets the batch size to be 24.
env.put(Context.BATCHSIZE, "24");
You can specify CORBA related properties such as those with the "org.omg.CORBA." prefix as properties. Properties of type String are used to initialize the ORB.
The properties that affect which ORB is used and how the
ORB is initialized are:
If the properties employed in steps (a), (b) and (c) contain
no relevant information for initializing the ORB, then the Java IDL
implementation's defaults are used. Typically that means port 900 on
the local host for an application, and port 900 on the applet host for
an applet are used.
Note that when the ORB is initialized using ORB.init(), its
arguments are checked in the following order: (from
org.omg.CORBA.ORB javadoc)
The root naming context is initialized either using the
java.naming.provider.url property or by a
resolve_initial_references()
call on the ORB. If the java.naming.provider.url property is set
but contains neither an "iiop" or "iiopname" URL, then it is assumed to contain
a stringified IOR, a "corbaname" or "corbaloc" URL of an IOR,
or a URL containing the location of a stringified
IOR. The IOR is used to obtain the root naming context and must
be that of a CORBA object of type
CosNaming::NamingContext.
If the java.naming.provider.url has not been set,
then the root naming context is
obtained by invoking the following method on the ORB:
String Names
String names accepted by the java.naming.Context methods
are
JNDI composite names
in which each component is the stringified form
of a CosNaming::NameComponent.
A CosNaming::Name
contains a sequence of CosNaming::NameComponent. The stringified
form of a component is the concatenation of the component's id, the kind
separator character ('.'), and the component's kind. The occurrence of
any meta characters ('.', '/', or '\') in either the id or kind is escaped
using the escape character ('\').
The stringified form of a CosNaming::Name is defined in Section
3.5 of the INS
specification (99-12-03).
The
JNDI composite name syntax
is very similar to, but not identical
to, the INS syntax. There are minor differences with respect to the
treatment of escape and quote characters. If you want to use names
with the precise INS syntax, then you should use the overloads that accept a
Name argument instead of a String argument. The
Name argument should be a value returned by
nameParser.parse(), where nameParser is a value obtained
from the COS naming service provider. See the Name
Parsing section.
URL String Names
The URL form of a CosNaming::Name is defined in the INS
specification.
For backward compatibility with older versions of the INS, the following
URL schemes are also supported.
where <addr_list> specifies a list of host/port pairs.
If <port> is not specified,
then it defaults to 9999. <cosnaming_name>
is the stringified form of an INS name.
If <port>
is not supplied, then it defaults to 900. <cosnaming_name>
is the stringified form of an INS name.
When you supply an "iiop" or "iiopname" URL to the initial context in this way,
the ORB supplied to the initial context is used
if its string_to_object() method supports the
99-12-03 INS specification.
Otherwise, the ORB is ignored and the server and port designations in
the URL are used to create an ORB.
The value of the java.naming.factory.initial
property is ignored for the purposes of resolving the URL.
Note that this rule is not used
when you supply a "corbaname" URL to the initial context.
For a "corbaname" URL, the ORB supplied to the initial context is used
because the ORB is needed to resolve the "corbaname" URL.
Name Objects
The Name argument to a Context method is treated as a
sequence of strings, each representing a stringified
CosNaming::NameComponent.
The COS naming service provider supports names in the syntax specified
in the INS specification. In short, the syntax is that components are
left-to-right slash ('/') separated and case-sensitive. The id and
kind of each component are separated by the period character ('.').
Here is a code fragment that uses the name parser from the COS naming
service provider to eventually do a lookup using an INS name.
The COS name server supports only naming operations. The COS naming
service provider maps the javax.naming.Context methods to use the
appropriate COS Naming calls.
If the object being bound is an
org.omg.CosNaming.NamingContext, then
CosNaming::NamingContext.bind_context is used. If it is an
org.omg.CORBA.Object, then CosNaming::NamingContext.bind
is used.
The binding of any other type of object is not supported unless the
object can be converted into an org.omg.CORBA.Object using
the state factory mechanism described next.
Before the bind is performed on the naming server, the COS naming
service provider uses javax.naming.spi.NamingManager.getStateToBind()
to allow the object to be transformed into a
org.omg.CORBA.Object. The getStateToBind() method uses
the state factories available to the COS naming service provider.
If the state factory accepts a java.rmi.Remote object, then it
is responsible for obtaining the object's RMI-IIOP stub and connecting
it to the ORB associated with the context. The connected stub is
the object that will be bound in the naming server.
By default, the COS naming service provider supplies and uses
a state factory that transforms an object implementing
the java.rmi.Remote interface to an org.omg.CORBA.Object
following the requirements described above. This factory
uses the utilities in the javax.rmi.CORBA package.
You can supply additional state factories
to transform objects into CORBA objects.
ORB Initialization
The following algorithm is used to determine which ORB is used:
java.naming.corba.orb
java.naming.applet
java.naming.provider.url
Root Naming Context Initialization
orb.resolve_initial_references("NameService");
Names and URLs
corbaname:<corbaloc_obj>["#" <cosnaming_name>]
where <corbaloc_obj> is
<corbaloc_obj> = <obj_addr_list> ["/" <key_string>]
and <obj_addr_list> is a list of addresses as defined in a
"corbaloc" URL and <key_string> is a key string as defined
in a "corbaloc" URL.
<cosnaming_name>
is the stringified form of an INS name (see
Name Parsing).
iiopname://[<addr_list>][/<cosnaming_name>]
iiop://<host>[:<port>][/<cosnaming_name>]
String insName = ...;
InitialContext ctx = new InitialContext(env); // env contains init properties
NameParser parser = ctx.getNameParser(""); // parser for INS names
Name name = parser.parse(insName); // get parsed INS name
Object obj = ctx.lookup(name); // do lookup
API Mapping
addToEnvironment()
Records change to environment property but does not reinitialize
ORB.
bind()
Binds an object to the specified name.
close()
Releases any internal data structures used.
composeName()
Concatenates the supplied name to the prefix.
createSubcontext()
Uses CosNaming::NamingContext.bind_new_context to create and bind
a new context.
destroySubcontext()
Uses CosNaming::NamingContext.destroy to destroy the named context.
Then uses CosNaming::NamingContext.unbind to remove the binding.
getEnvironment()
Returns the environment of this context.
getNameInNamespace()
Returns the INS name of this context relative to the root of the
Cos Naming namespace.
getNameParser()
Returns a name parser for parsing INS names.
lookup()
lookupLink()
Uses CosNaming::NamingContext.resolve to lookup the name.
It returns a CORBA object reference except when the reference is
that of a CosNaming::NamingContext, in which case a
Context object is returned instead.
NamingManager.getObjectInstance()
is called before the object is returned in case the application
or user has supplied object factories.
list()
listBindings()
Uses CosNaming::NamingContext.resolve to get the object reference
for the context,
and then uses CosNaming::BindingIterator and helper classes to iterate
through the context.
The objects bound to the names are obtained by calling
CosNaming::NamingContext.resolve on them.
NamingManager.getObjectInstance()
is called before the object is returned in case the application
or user has supplied object factories.
removeFromEnvironment()
Removes the specified property from the environment but
does not otherwise update the context.
rebind()
If the object being bound is an
org.omg.CosNaming.NamingContext, then
CosNaming::NamingContext.rebind_context is used. If it is an
org.omg.CORBA.Object, then CosNaming::NamingContext.rebind is
used. See bind() for details on the use of state factories
to transform the argument into an org.omg.CORBA.Object.
rename()
This method is implemented using bind() followed by
unbind(). It is not atomic.
unbind()
Uses CosNaming::NamingContext.unbind to unbind the object.