The Java Naming and Directory Interface (JNDI) API is used for accessing different kinds of naming and directory services. Java EE components locate objects by invoking the JNDI lookup method.
The following topics are addressed here:
Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.
By making calls to the JNDI API, applications locate resources and other program objects. A resource is a program object that provides connections to systems, such as database servers and messaging systems. A JDBC resource is sometimes referred to as a data source. Each resource object is identified by a unique, people-friendly name, called the JNDI name. A resource object and its JNDI name are bound together by the naming and directory service, which is included with the GlassFish Server.
When a new name-object binding is entered into the JNDI, a new resource is created.
The following topics are addressed here:
JNDI names are bound to their objects by the naming and directory service that is provided by a Java EE server. Because Java EE components access this service through the JNDI API, the object usually uses its JNDI name. For example, the JNDI name of the PointBase database is jdbc/Pointbase. At startup, the GlassFish Server reads information from the configuration file and automatically adds JNDI database names to the name space, one of which is jdbc/Pointbase.
Java EE application clients, enterprise beans, and web components must have access to a JNDI naming environment.
The application component's naming environment is the mechanism that allows customization of the application component's business logic during deployment or assembly. This environment allows you to customize the application component without needing to access or change the source code off the component. A Java EE container implements the provides the environment to the application component instance as a JNDI naming context.
The application component's environment is used as follows:
The application component's business methods access the environment using the JNDI interfaces. In the deployment descriptor, the application component provider declares all the environment entries that the application component expects to be provided in its environment at runtime.
The container provides an implementation of the JNDI naming context that stores the application component environment. The container also provides the tools that allow the deployer to create and manage the environment of each application component.
A deployer uses the tools provided by the container to initialize the environment entries that are declared in the application component's deployment descriptor. The deployer sets and modifies the values of the environment entries.
The container makes the JNDI context available to the application component instances at runtime. These instances use the JNDI interfaces to obtain the values of the environment entries.
Each application component defines its own set of environment entries. All instances of an application component within the same container share the same environment entries. Application component instances are not allowed to modify the environment at runtime.
A resource reference is an element in a deployment descriptor that identifies the component’s coded name for the resource. For example, jdbc/SavingsAccountDB. More specifically, the coded name references a connection factory for the resource.
The JNDI name of a resource and the resource reference name are not the same. This approach to naming requires that you map the two names before deployment, but it also decouples components from resources. Because of this decoupling, if at a later time the component needs to access a different resource, the name does not need to change. This flexibility makes it easier for you to assemble Java EE applications from preexisting components.
The following table lists JNDI lookups and their associated resource references for the Java EE resources used by the GlassFish Server.
Table 20–1 JNDI Lookup Names and Their Associated References
JNDI Lookup Name |
Associated Resource Reference |
---|---|
java:comp/env |
Application environment entries |
java:comp/env/jdbc |
JDBC DataSource resource manager connection factories |
java:comp/env/ejb |
EJB References |
java:comp/UserTransaction |
UserTransaction references |
java:comp/env/mail |
JavaMail Session Connection Factories |
java:comp/env/url |
URL Connection Factories |
java:comp/env/jms |
JMS Connection Factories and Destinations |
java:comp/ORB |
ORB instance shared across application components |
Within GlassFish Server, you can configure your environment for custom and external JNDI resources. A custom resource accesses a local JNDI repository; an external resource accesses an external JNDI repository. Both types of resources need user-specified factory class elements, JNDI name attributes, and so on.
A custom resource specifies a custom server-wide resource object factory that implements the javax.naming.spi.ObjectFactory interface.
The following topics are addressed here:
Use the create-custom-resource subcommand in remote mode to create a custom resource.
Ensure that the server is running.
Remote subcommands require a running server.
Create a custom resource by using the create-custom-resource(1) subcommand.
Information on properties for the subcommand is contained in this help page.
Restart GlassFish Server.
See To Restart a Domain.
This example creates a custom resource named sample-custom-resource.
asadmin> create-custom-resource --restype topic --factoryclass com.imq.topic sample_custom_resource Command create-custom-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-custom-resource at the command line.
Use the list-custom-resources subcommand in remote mode to list the existing custom resources.
Ensure that the server is running.
Remote subcommands require a running server.
List the custom resources by using the list-custom-resources(1) subcommand.
This example lists the existing custom resources.
asadmin> list-custom-resources sample_custom_resource01 sample_custom_resource02 Command list-custom-resources executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-custom-resources at the command line.
List the custom resources by using the list-custom-resources(1) subcommand.
Use the set(1) subcommand to modify a custom JNDI resource.
This example modifies a custom resource.
asadmin> set server.resources.custom-resource.custom /my-custom-resource.property.value=2010server.resources.custom-resource.custom /my-custom-resource.property.value=2010 |
Use the delete-custom-resource subcommand in remote mode to delete a custom resource.
Ensure that the server is running.
Remote subcommands require a running server.
List the custom resources by using the list-custom-resources(1) subcommand.
Delete a custom resource by using the delete-custom-resource(1) subcommand.
This example deletes a custom resource named sample-custom-resource.
asadmin> delete-custom-resource sample_custom_resource Command delete-custom-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-custom-resource at the command line.
Applications running on GlassFish Server often require access to resources stored in an external JNDI repository. For example, generic Java objects might be stored in an LDAP server according to the Java schema. External JNDI resource elements let you configure such external resource repositories.
The following topics are addressed here:
Use the create-jndi-resource subcommand in remote mode to register an external JNDI resource.
The external JNDI factory must implement the javax.naming.spi.InitialContextFactory interface.
Ensure that the server is running.
Remote subcommands require a running server.
Register an external JNDI resource by using the create-jndi-resource(1) subcommand.
Information on properties for the subcommand is contained in this help page.
Restart GlassFish Server.
See To Restart a Domain.
In This example sample_jndi_resource is registered.
asadmin> create-jndi-resource --jndilookupname sample_jndi --restype queue --factoryclass sampleClass --description "this is a sample jndi resource" sample_jndi_resource Command create-jndi-resource executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jndi-resource at the command line.
Use the list-jndi-resources subcommand in remote mode to list all existing JNDI resources.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JNDI resources by using thelist-jndi-resources(1) subcommand.
This example lists the JNDI resources.
asadmin> list-jndi-resources jndi_resource1 jndi_resource2 jndi_resource3 Command list-jndi-resources executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jndi-resources at the command line.
Use the list-jndi-entries subcommand in remote mode to browse and list the entries in the JNDI tree. You can either list all entries, or you can specify the JNDI context or subcontext to list specific entries.
Ensure that the server is running.
Remote subcommands require a running server.
List the JNDI entries for a configuration by using the list-jndi-entries(1) subcommand.
This example lists all the JNDI entries for the naming service.
asadmin> list-jndi-entries jndi_entry03 jndi_entry72 jndi_entry76 Command list-jndi-resources executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jndi-entries at the command line.
List the existing JNDI resources by using thelist-jndi-resources(1) subcommand.
Use the set(1) subcommand to modify an external JNDI resource.
This example modifies an external resource.
asadmin> set server.resources.external-jndi-resource.my-jndi-resource. jndi-lookup-name=bar server.resources.external-jndi-resource.my-jndi-resource.jndi-lookup-name=bar |
Use the delete-jndi-resource subcommand in remote mode to remove a JNDI resource.
Ensure that the server is running.
Remote subcommands require a running server.
Remove an external JNDI entry by using the delete-jndi-resource(1) subcommand.
This example deletes an external JNDI resource:
asadmin> delete-jndi-resource jndi_resource2 Command delete-jndi-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jndi-resource at the command line.
<resources> <!-- external-jndi-resource element specifies how to access Java EE resources -- stored in an external JNDI repository. This example -- illustrates how to access a java object stored in LDAP. -- factory-class element specifies the JNDI InitialContext factory that -- needs to be used to access the resource factory. property element -- corresponds to the environment applicable to the external JNDI context -- and jndi-lookup-name refers to the JNDI name to lookup to fetch the -- designated (in this case the java) object. --> <external-jndi-resource jndi-name="test/myBean" jndi-lookup-name="cn=myBean" res-type="test.myBean" factory-class="com.sun.jndi.ldap.LdapCtxFactory"> <property name="PROVIDER-URL" value="ldap://ldapserver:389/o=myObjects" /> <property name="SECURITY_AUTHENTICATION" value="simple" /> <property name="SECURITY_PRINCIPAL", value="cn=joeSmith, o=Engineering" /> <property name="SECURITY_CREDENTIALS" value="changeit" /> </external-jndi-resource> </resources>