Chapter 11 Using the Java Naming and Directory Interface

A naming service maintains a set of bindings, which relate names to objects. The Java EE naming service is based on the Java Naming and Directory Interface^TM (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 http://java.sun.com/products/jndi/.

You can also see the JNDI tutorial at http://java.sun.com/products/jndi/tutorial/.

This chapter contains the following sections:

• Accessing the Naming Context

• Mapping References

For GlassFish v3 Prelude, EJB modules are not supported unless the optional EJB container add-on component is downloaded from the Update Tool. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

For GlassFish v3 Prelude, only stateless session beans with local interfaces and entity beans that use the Java Persistence API are supported. Stateful, message-driven, and EJB 2.0 and 2.1 entity beans are not supported. Remote interfaces and remote business interfaces for any of the bean types are not supported.

Accessing the Naming Context

The Enterprise Server provides a naming environment, or context, which is compliant with standard Java EE 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 Java EE 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.

Each resource within the server must have a unique name.

Global JNDI Names

Global JNDI names are assigned according to the following precedence rules:

1. A global JNDI name assigned in the sun-ejb-jar.xml, sun-web.xml deployment descriptor file has the highest precedence. See Mapping References.

2. A global JNDI name assigned in a mapped-name element in the ejb-jar.xml, web.xml deployment descriptor file has the second highest precedence. The following elements have mapped-name subelements: resource-ref, resource-env-ref, ejb-ref, message-destination, message-destination-ref, session, and entity.

3. A global JNDI name assigned in a mappedName attribute of an annotation has the third highest precedence. The following annotations have mappedName attributes: @javax.annotation.Resource, @javax.ejb.EJB, @javax.ejb.Stateless.

4. A default global JNDI name is assigned in some cases if no name is assigned in deployment descriptors or annotations.

   • For component dependencies that must be mapped to global JNDI names, the default is the name of the dependency relative to java:comp/env. For example, in the @Resource(name="jdbc/Foo") DataSource ds; annotation, the global JNDI name is jdbc/Foo.

Using a Custom jndi.properties File

To use a custom jndi.properties file, place the file in the domain-dir/lib/classes directory or JAR it and place it in the domain-dir/lib directory. This adds the custom jndi.properties file to the Common class loader. For more information about class loading, see Chapter 2, Class Loaders.

For each property found in more than one jndi.properties file, the Java EE naming service either uses the first value found or concatenates all of the values, whichever makes sense.

Mapping References

The following XML elements in the Enterprise Server deployment descriptors map resource references in EJB and web application components to JNDI names configured in the Enterprise Server:

• resource-env-ref - Maps the @Resource or @Resources annotation (or the resource-env-ref element in the corresponding Java EE XML file) to the absolute JNDI name configured in the Enterprise Server.

• resource-ref - Maps the @Resource or @Resources annotation (or the resource-ref element in the corresponding Java EE XML file) to the absolute JNDI name configured in the Enterprise Server.

• ejb-ref - Maps the @EJB annotation (or the ejb-ref element in the corresponding Java EE XML file) to the absolute JNDI name configured in the Enterprise Server.

  JNDI names for EJB components must be unique. For example, appending the application name and the module name to the EJB name is 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.xml and sun-ejb-ref.xml deployment descriptor files. For more information about how these elements behave in each of the deployment descriptor files, see Appendix A, Deployment Descriptor Files, in Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.

The rest of this section uses an example of a JDBC resource lookup to describe how to reference resource factories.

The @Resource annotation in the application code looks like this:

@Resource(name="jdbc/helloDbDs") javax.sql.DataSource ds;

This references a resource with the JNDI name of java:comp/env/jdbc/helloDbDs. If this is the JNDI name of the JDBC resource configured in the Enterprise Server, the annotation alone is enough to reference the resource.

However, you can use an Enterprise Server specific deployment descriptor to override the annotation. For example, the resource-ref element in the sun-web.xml file maps the res-ref-name (the name specified in the annotation) to the JNDI name of another JDBC resource configured in the Enterprise Server.

<resource-ref>
   <res-ref-name>jdbc/helloDbDs</res-ref-name>
   <jndi-name>jdbc/helloDbDataSource</jndi-name>
</resource-ref>