Chapter 13 Using the Java Naming and Directory Interface

A naming service maintains a set of bindings, which relate names to objects. The J2EE™ naming service is based on the Java Naming and Directory Interface™ (JNDI) API. The JNDI API allows application components and clients to look up distributed resources, services, and EJB™ components. For general information about the JNDI API, see:

Accessing the Naming Context

Sun Java ™ System Application Server provides a naming environment, or context, which is compliant with standard J2EE 1.4 requirements. A Context object provides the methods for binding names to objects, unbinding names from objects, renaming objects, and listing the bindings. The InitialContext is the handle to the J2EE naming service that application components and clients use for lookups.

The JNDI API also provides subcontext functionality. Much like a directory in a file system, a subcontext is a context within a context. This hierarchical structure permits better organization of information. For naming services that support subcontexts, the Context class also provides methods for creating and destroying subcontexts.

Naming Environment for J2EE Application Components


Note	Each resource within a server instance must have a unique name. However, two resources in different server instances or different domains may have the same name.

The namespace for objects looked up in a J2EE environment is organized into different subcontexts, with the standard prefix java:comp/env.

The following table describes standard JNDI subcontexts for connection factories in the Sun Java System Application Server.

Table 13-1 Standard JNDI Subcontexts for Connection Factories
Resource Manager	Connection Factory Type	JNDI Subcontext
JDBC™	javax.sql.DataSource	java:comp/env/jdbc
Transaction Service	javax.transaction.UserTransaction	java:comp/UserTransaction
JMS	javax.jms.TopicConnectionFactory javax.jms.QueueConnectionFactory	java:comp/env/jms
JavaMail™	javax.mail.Session	java:comp/env/mail
URL	java.net.URL	java:comp/env/url
Connector	javax.resource.cci.ConnectionFactory	java:comp/env/eis

Accessing EJB Components Using the CosNaming Naming Context

The preferred way of accessing the naming service, even in code that runs outside of a J2EE container, is to use the no-argument InitialContext constructor. However, if EJB client code explicitly instantiates an InitialContext that points to the CosNaming naming service, it is necessary to set three properties in the client JVM when accessing EJB components:

Accessing EJB Components in a Remote Application Server

The recommended approach for looking up an EJB component in a remote Application Server from a client that is a servlet or EJB component is to use the Interoperable Naming Service syntax. Host and port information is prepended to any global JNDI names and is automatically resolved during the lookup. The syntax for an interoperable global name is as follows:

This makes the programming model for accessing EJB components in another Application Server exactly the same as accessing them in the same server. The deployer can change the way the EJB components are physically distributed without having to change the code.

For J2EE components, the code still performs a java:comp/env lookup on an EJB reference. The only difference is that the deployer maps the ejb-reference element to an interoperable name in an Application Server deployment descriptor file instead of a simple global JNDI name.

For example, suppose a servlet looks up an EJB reference using java:comp/env/ejb/Foo, and the target EJB component has a global JNDI name of a/b/Foo.

<ejb-ref>
<ejb-ref-name>ejb/Foo</ejb-ref-name>
<jndi-name>corbaname:iiop:host:port#a/b/Foo</jndi-name>
<ejb-ref>

Context ic = new InitialContext();
Object o = ic.lookup("java:comp/env/ejbFoo");

For a client that doesn’t run within a J2EE container, the code just uses the interoperable global name instead of the simple global JNDI name. For example:

Context ic = new InitialContext();
Object o = ic.lookup("corbaname:iiop:host:port#a/b/Foo");

Objects stored in the interoperable naming context and component-specific (java:comp/env) naming contexts are transient. On each server startup or application reloading, all relevant objects are re-bound to the namespace.

Naming Environment for Lifecycle Modules

Lifecycle listener modules provide a means of running short or long duration Java-based tasks within the application server environment, such as instantiation of singletons or RMI servers. These modules are automatically initiated at server startup and are notified at various phases of the server life cycle. For details about lifecycle modules, see Chapter 10, "Developing Lifecycle Listeners."

The configured properties for a lifecycle module are passed as properties during server initialization (the INIT_EVENT). The initial JNDI naming context is not available until server initialization is complete. A lifecycle module can get the InitialContext for lookups using the method LifecycleEventContext.getInitialContext() during, and only during, the STARTUP_EVENT, READY_EVENT, or SHUTDOWN_EVENT server life cycle events.

Configuring Resources

Sun Java System Application Server exposes the following special resources in the naming environment. Full administration details are provided in the following sections:

External JNDI Resources

An external JNDI resource defines custom JNDI contexts and implements the javax.naming.spi.InitialContextFactory interface. There is no specific JNDI parent context for external JNDI resources, except for the standard java:comp/env/.

The “Using The Administration Console” section describes each connection pool setting. The “Using The Command Line Interface” section merely lists syntax and default values.

Using the Administration Console

To create an external JNDI resource using the Administration Console, perform the following tasks:

http://host:port/asadmin

For example:

http://localhost:4848/asadmin

Open the JNDI component.

Click External Resources.

Click the New button.

Enter the following information:

JNDI Name (required) - Enter the JNDI name for the resource.

Resource Type (required) - Enter the fully qualified type of the resource.

JNDI Lookup (required) - Enter the JNDI value to look up in the external repository. For example, for a bean class, your JNDI Lookup might be cn=mybean.

Factory Class (required) - Enter the fully qualified name of the factory class.

Description (optional) - You can enter a text description of the external JNDI resource.

Check the Status Enabled box to enable the external JNDI resource. If an external JNDI resource is disabled, no application component can connect to it, but its configuration remains in the domain.

To add a property, click the Add Property button and enter the property name and value. To delete properties, check the properties you want to delete, then click the Delete Properties button.

Click the OK button.

Using the Command Line Interface

To create an external JNDI resource using the command line, use the asadmin create-jndi-resource command. The syntax is as follows, with defaults shown for optional parameters that have them:

asadmin create-jndi-resource --user user --jndilookupname lookup_name --restype resource_type --factoryclass class_name [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndi_name

For more information about the optional general asadmin parameters (--password, --passwordfile, --host, --port, --secure, --terse, --echo, and --interactive), see the Sun Java System Application Server Administration Guide.

asadmin create-jndi-resource --user joeuser --jndilookupname cn=myBean --restype test.myBean --factoryclass com.sun.jndi.ldap.LdapCtxFactory test/myBean

Custom Resources

A custom resource specifies a custom server-wide resource object factory that implements the javax.naming.spi.ObjectFactory interface. There is no specific JNDI parent context for external JNDI resources, except for the standard java:comp/env/.

The “Using The Administration Console” section describes each connection pool setting. The “Using The Command Line Interface” section merely lists syntax and default values.

Using the Administration Console

To create a custom resource using the Administration Console, perform the following tasks:

http://host:port/asadmin

For example:

http://localhost:4848/asadmin

Open the JNDI component.

Click Custom Resources.

Click the New button.

Enter the following information:

JNDI Name (required) - Enter the JNDI name for the resource.

Resource Type (required) - Enter the fully qualified type of the resource.

Factory Class (required) - Enter the fully qualified name of the factory class.

Description (optional) - You can enter a text description of the custom resource.

Check the Custom Resource Enabled box to enable the custom resource. If a custom resource is disabled, no application component can connect to it, but its configuration remains in the domain.

To add a property, click the Add Property button and enter the property name and value. To delete properties, check the properties you want to delete, then click the Delete Properties button.

Click the OK button.

Using the Command Line Interface

To create a custom resource using the command line, use the asadmin create-custom-resource command. The syntax is as follows, with defaults shown for optional parameters that have them:

asadmin create-custom-resource --user user --restype resource_type --factoryclass class_name [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndi_name

asadmin create-custom-resource --user joeuser --restype test.MyBean --factoryclass test.MyBeanFactory test/myBean

Mapping References

The following XML elements map JNDI names configured in the Sun Java System Application Server to resource references in application client, EJB, and web application components:

resource-env-ref - Maps the resource-env-ref element in the corresponding J2EE XML file to the absolute JNDI name configured in Sun Java System Application Server.

resource-ref - Maps the resource-ref element in the corresponding J2EE XML file to the absolute JNDI name configured in Sun Java System Application Server.

ejb-ref - Maps the ejb-ref element in the corresponding J2EE XML file to the absolute JNDI name configured in Sun Java System Application Server.

JNDI names for EJB components must be unique. For example, appending the application name and the module name to the EJB name would be one way to guarantee unique names. In this case, mycompany.pkging.pkgingEJB.MyEJB would be the JNDI name for an EJB in the module pkgingEJB.jar, which is packaged in the pkging.ear application.

These elements are part of the sun-web-app.xml, sun-ejb-ref.xml, and sun-application-client.xml deployment descriptor files. For more information about how these elements behave in each of the deployment descriptor files, see Chapter 5, “Deployment Descriptor Files.”

The rest of this section uses an example of a JDBC resource lookup to describe how to reference resource factories. The same principle is applicable to all resources (such as JMS destinations, JavaMail sessions, and so on).

The resource-ref element in the sun-web-app.xml deployment descriptor file maps the JNDI name of a resource reference to the resource-ref element in the web-app.xml J2EE deployment descriptor file.

InitialContext ic = new InitialContext();
String dsName = "java:comp/env/jdbc/HelloDbDs";
DataSource ds = (javax.sql.DataSource)ic.lookup(dsName);
Connection connection = ds.getConnection();

The resource being queried is listed in the res-ref-name element of the web.xml file as follows:

<resource-ref>
  <description>DataSource Reference</description>
  <res-ref-name>jdbc/HelloDbDs</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
</resource-ref>

The resource-ref section in a Sun Java System specific deployment descriptor, for example sun-web.xml, maps the res-ref-name (the name being queried in the application code) to the JNDI name of the JDBC resource. The JNDI name is the same as the name of the JDBC resource as defined in the resource file when the resource is created.

<resource-ref>
<res-ref-name>jdbc/HelloDbDs</res-ref-name>
<jndi-name>jdbc/HelloDbDataSource</jndi-name>
</resource-ref>

The JNDI name in the Sun Java System specific deployment descriptor must match the JNDI name you assigned to the resource when you created and configured it.

Previous Contents Index Next
Sun Java System Application Server Platform Edition 8 Developer's Guide