Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to J2EE Services and APIs

> ## Chapter 4
> 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:

> 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
> - Configuring Resources
> - Mapping References
> - Sample Applications

> ##

> Accessing the Naming Context

> Sun Java™ System Application Server provides a naming environment, or context, which is compliant with standard J2EE 1.3 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.

> The rest of this section covers these topics:

> - Using the InitialContext to Look Up a Named Object
> - Naming Environment for J2EE Application Components
> - COSNaming Provider for Application Clients
> - Naming Environment for Lifecycle Modules

> ### Using the InitialContext to Look Up a Named Object

> To look up a resource, first you instantiate an InitialContext, then you use the InitialContext.lookup() method to look up the resource by its JNDI name. The following example catches NameNotFoundException and NamingException exceptions that can occur during a lookup:

> try {
> InitialContext ic = new InitialContext();
> String snName = "java:comp/env/mail/MyMailSession";
> Session session = (javax.mail.Session)ic.lookup(snName);
> }
> catch (NameNotFoundException e) {
> out("\nJNDI binding was not found");
> }
> catch (NamingException e) {
> out("\nJNDI binding error");
> }

> ### Naming Environment for J2EE Application Components

> 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 4-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

> ### COSNaming Provider for Application Clients

> To support a global JNDI namespace that is accessible to IIOP application clients, Sun Java System Application Server includes a J2EE-based CosNaming provider, which supports the binding of CORBA references (remote EJB references). The InitialContext returned to the IIOP clients is a CosNaming provider. A Sun Java System Application Server instance registers the entity beans for the IIOP clients to lookup and bind to.

> Objects stored in the CosNaming and local JNDI environments 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 the Sun Java System Application Server Developer’s Guide.

> 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

> J2EE application components can access a variety of resources using the JNDI API, such as:

> - JDBC Resources
> - User Transaction Handles
> - JMS Resources
> - JavaMail Sessions
> - Persistence Manager Factories
> - URL Connection Factories
> - J2EE Connector Architecture Connection Factories

> In addition, Sun Java System Application Server exposes the following resources in the naming environment. For these resources, full administration details are provided in the following sections:

> - External JNDI Resources
> - Custom Resources

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

> ### JDBC Resources

> For details on how to configure JDBC resources, see “General Steps for Creating a JDBC Resource” on page 20. The standard JNDI subcontext for JDBC resources is java:comp/env/jdbc. For more information, see “Looking Up a JDBC Resource” on page 42.

> ### User Transaction Handles

> Application components obtain reference to the container’s default transaction coordinator by doing a JNDI lookup of java:comp/UserTransaction. The returned object implements the javax.transaction.UserTransaction interface and can be used in the application to begin, commit, rollback, and query the status of transactions. For additional information about transactions, see Chapter 3, “Using the Transaction Service.”

> ### JMS Resources

> For details on how to configure JMS resources, see “Administration of the JMS Service” on page 76. The standard JNDI subcontext for JMS resources is java:comp/env/jms. For more information, see “Looking Up Connection Factories” on page 86 and “Looking Up Destinations” on page 87.

> ### JavaMail Sessions

> For details on how to configure JavaMail sessions, see “Creating a JavaMail Session” on page 96. The standard JNDI subcontext for JavaMail sessions is java:comp/env/mail. For more information, see “Looking Up a JavaMail Session” on page 99.

> ### Persistence Manager Factories

> A persistence manager factory resource for container-managed persistence (CMP) implements the following interface:

> com.sun.jdo.spi.persistence.support.sqlstore.impl.PersistenceManagerFactory

> The standard JNDI subcontext for persistence manager factories is java:comp/env/jdo.

> For details about how to create and use a persistence manager factory resource, see the Sun Java System Application Server Administrator’s Guide and the Sun Java System Application Server Developer’s Guide to Enterprise JavaBeans Technology.

> ### URL Connection Factories

> A URL connection factory implements the java.net.URL interface. The standard JNDI subcontext for URL connection factories is java:comp/env/url.

> URL connection factories do not require any resource to be configured in the Sun Java System Application Server itself. The jndi-name element in the relevant deployment descriptor specifies the target URL. For example, the following entry in the web.xml file:

> <resource-ref>
> <res-ref-name>myURL</res-ref-name>
> <res-type>java.net.URL</res-type>
> <res-auth>Container</res-auth>
> </resource-ref>

> maps to the following entry in the sun-web.xml file:

> <resource-ref>
> <res-ref-name>myURL</res-ref-name>
> <jndi-name>http://www.sun.com/index.html</jndi-name>
> </resource-ref>

> ### J2EE Connector Architecture Connection Factories

> A J2EE™ Connector Architecture (CA) connection factory implements the javax.resource.cci.ConnectionFactory interface.

> The standard JNDI subcontext for J2EE CA connection factory resources is java:comp/env/eis.

> For details about how to create and use a J2EE CA connection factory, see the Sun Java System Application Server J2EE CA Service Provider Implementation Administrator’s Guide.

> ### 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/.

> Create an external JNDI resource in one of these ways:

> - Using the Administration Interface
> - Using the Command Line Interface

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

> #### Using the Administration Interface

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

> 1. Open the JNDI component under your server instance.
> 2. Click External Resources.
> 3. Click the New button.
> 4. 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.
> 5. Check the External Resource 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 server instance.

> 6. Click the OK button.
> 7. To add properties to an external JNDI resource, perform the following tasks:
> 1. Go back to the External Resources page.
> 2. Click the external JNDI resource you just created.
> 3. Click the Properties button.
> 4. Specify names and values for any properties you want to use. If you need another name-value row, use the Add button to add it.
> 5. Click the OK button.
> 6. Click the Save button.
> 8. Go to the server instance page.
> 9. Click the General tab.
> 10. Click the Apply Changes 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 admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] --jndilookupname lookup_name --resourcetype resource_type --factoryclass class_name [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndi_name

> For more information about the parameters specific to asadmin create-jndi-resource, see Using the Administration Interface. For more information about the general asadmin parameters (--user, --password, --passwordfile, --host, --port, and --secure), see the Sun Java System Application Server Administrator’s Guide.

> For example:

> asadmin create-jndi-resource --user joeuser --password secret --jndilookupname cn=myBean --resourcetype test.myBean --factoryclass com.sun.jndi.ldap.LdapCtxFactory test/myBean

> To delete an external JNDI resource, use the following command:

> asadmin delete-jndi-resource --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] jndi_name

> For example:

> asadmin delete-jndi-resource --user joeuser --password secret test/myBean

> To list external JNDI resources, use the following command:

> asadmin list-jndi-resources --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] --instance instance_name

> For example:

> asadmin list-jndi-resources --user joeuser --password secret --instance server1

> After you create the external JNDI resource, you must reconfigure the server instance using the following command:

> asadmin reconfig --user user [--password password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s][--discardmanualchanges=false | --keepmanualchanges=false] instance_name

> For example:

> asadmin reconfig --user joeuser --password secret server1

> ### 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/.

> Create a custom resource in one of these ways:

> - Using the Administration Interface
> - Using the Command Line Interface

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

> #### Using the Administration Interface

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

> 1. Open the JNDI component under your server instance.
> 2. Click Custom Resources.
> 3. Click the New button.
> 4. 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.
> 5. 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 server instance.

> 6. Click the OK button.
> 7. To add properties to a custom resource, perform the following tasks:
> 1. Go back to the Custom Resources page.
> 2. Click the custom resource you just created.
> 3. Click the Properties button.
> 4. Specify names and values for any properties you want to use. If you need another name-value row, use the Add button to add it.
> 5. Click the OK button.
> 6. Click the Save button.
> 8. Go to the server instance page.
> 9. Click the General tab.
> 10. Click the Apply Changes 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 admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] --resourcetype resource_type --factoryclass class_name [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndi_name

> For more information about the parameters specific to asadmin create-custom-resource, see Using the Administration Interface. For more information about the general asadmin parameters (--user, --password, --passwordfile, --host, --port, and --secure), see the Sun Java System Application Server Administrator’s Guide.

> For example:

> asadmin create-custom-resource --user joeuser --password secret --resourcetype test.MyBean --factoryclass test.MyBeanFactory test/myBean

> To delete a custom resource, use the following command:

> asadmin delete-custom-resource --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] jndi_name

> For example:

> asadmin delete-custom-resource --user joeuser --password secret test/myBean

> To list custom resources, use the following command:

> asadmin list-custom-resources --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] --instance instance_name

> For example:

> asadmin list-custom-resources --user joeuser --password secret --instance server1

> After you create the custom resource, you must reconfigure the server instance using the following command:

> asadmin reconfig --user user [--password password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s][--discardmanualchanges=false | --keepmanualchanges=false] instance_name

> For example:

> asadmin reconfig --user joeuser --password secret server1

> ##

> 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 the manuals listed in the following table.

> Table 4-2 Manuals that Document the Sun Java System Application Server Deployment Descriptors

> Deployment Descriptor | Where to Find More Information
> --- | ---
> sun-web.xml | Sun Java System Application Server Developer’s Guide to Web Applications
> sun-ejb-jar.xml | Sun Java System Application Server Developer’s Guide to Enterprise JavaBeans Technology
> sun-application-client.xml | Sun Java System Application Server Developer’s Guide to Clients

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

> The resource lookup in the application code looks like this:

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

> ##

> Sample Applications

> JNDI sample applications are in the following directory:

> install_dir/samples/jndi

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.