COS Naming Service Provider for the
Java Naming and Directory Interface^TM (JNDI)

Please send feedback to jndi@java.sun.com

Table of Contents

• Introduction
• Conformance
• Environment Properties
• ORB Initialization
• Root Naming Context Initialization
• Names and URLs
• API Mapping
• Converting CORBA Programs to use JNDI
• Security Considerations

Introduction

Conformance

The COS naming service provider for JNDI uses Java^TM 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 Server (INS) specification, OMG TC Document orbos/98-10-11. This is described in Names and URLs.

Environment Properties

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.

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.

For example:

env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.cosnaming.CNCtxFactory");

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.

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.

If the URL scheme is either "iiop" or "iiopname", the host and port fields of the URL are used to initialize the ORB. An "iiopname" URL must conform to the INS specification. It has the form:

iiopname://[<addr_list>][/<cosnaming name>]

An "iiop" URL is supported for backward compatibility with an older version of the INS specification. It has the form:

iiop://[<host>[:<port>]][/<cosnaming name>]

For both "iiop" and "iiopname" URLs, if the host is not specified, it defaults to "localhost" for an application and the applet's host for an applet. If the port is not specified, it defaults to 9999 for "iiopname", and 900 for "iiop". The root naming context is obtained by invoking the following method on the ORB:

orb.resolve_initial_references("NameService");

If the "cosnaming name" is nonempty, the root naming context is the naming context named by "cosnaming name".

If the URL scheme is "IOR", the property must contain the stringified IOR of the root naming context.

If the URL scheme is neither "iiop", "iiopname", nor "IOR", 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", 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). See the java.net.URL class for details. The stringified IOR is read from the data stream corresponding to the URL assuming 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", the headers in the stream are skipped and the first line containing the prefix "IOR:" is returned as the IOR.

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 intiailization properties.

If this property is not specified, the ORB is initialized using the java.naming.corba.orb property, the java.naming.applet property, or other ORB intiailization properties. The root naming context is obtained by invoking

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 applcation you can set this property as follows:

ORB orb = ORB.init(args, null);
Hashtable env = new Hashtable(5, 0.75f);
env.put("java.naming.corba.orb", orb);
...
    

In an applet, you can set it as follows:

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);
        ...
    }
...
}
    

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.

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 using RMI-IIOP. You can supply other factories to effect 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."

For 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.

ORB Initialization

Root Naming Context Initialization

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, it is assumed to contain a stringified IOR or a URL containing the location of a stringified IOR. The stringified IOR is used to obtain the root naming context. The stringified IOR must be that of a CORBA object of type CosNaming::NamingContext.

If the java.naming.provider.url has not been set or does not contain a stringified IOR or its location, the root naming context is obtained by invoking the following method on the ORB:

        orb.resolve_initial_references("NameService");

Names and URLs

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 4.5 of the INS specification.

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 are want to use names with the precise INS syntax, 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.

iiopname://[<addr_list>][/<cosnaming name>]

where addr_list specifies a list of host/port pairs. If the port is not specified, it defaults to 9999. <cosnaming name> is the stringified form of an INS name (see Name Parsing).

For backward compatibility with an older INS specification, the following URL is also supported

iiop://<host>[:<port>][/<cosnaming name>]

If port is not supplied, it defaults to 900. <cosnaming name> is the stringified form of an INS name (see Name Parsing).

When you supply the URL to the initial context in this way, the ORB supplied to the initial context is ignored. In fact, the values of the java.naming.factory.initial and java.naming.corba.orb properties are ignored.

For example, the following code will contact the naming service running on host 'server', at port '1900', and lookup the INS name "some/cos/name".

InitialContext ictx = new InitialContext();   
Object helloRef = ictx.lookup("iiopname://server:1900/some/cos/name");

Name Objects

The Name argument to a Context method is treated as a sequence of strings, each representing a stringified CosNaming::NameComponent.

Name Parsing

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.

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()

bind()

close()

composeName()

createSubcontext()

destroySubcontext()

getEnvironment()

getNameInNamespace()

getNameParser()

lookup()
lookupLink()

list()
listBindings()

removeFromEnvironment()

rebind()

rename()

unbind()

Converting CORBA Programs to use JNDI

Security Considerations

permission java.net.SocketPermission "host[:port]", "connect";