Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide

- Previous: Chapter 5 Configuring JavaMail Resources
- Next: Chapter 7 Connector Resources

# Chapter 6 JNDI Resources

- About Java Naming and Directory Interface (JNDI)

- About Custom Resources

- About External JNDI Repositories and Resources

# About Java Naming and Directory Interface (JNDI)

This section discusses the Java Naming and Directory Interface (JNDI). JNDI is an application programming interface (API) for accessing different kinds of naming and directory services. J2EE components locate objects by invoking the JNDI lookup method.

This section covers the following topics:

- JNDI Names and Resources

- J2EE Naming Services

- Naming References and Binding Information

## JNDI Names and Resources

JNDI is the acronym for the Java Naming and Directory Interface API. By making calls to this 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 Application Server. To create a new resource, a new name-object binding is entered into the JNDI.

## J2EE Naming Services

A JNDI name is a people-friendly name for an object. These names are bound to their objects by the naming and directory service that is provided by a J2EE server. Because J2EE 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`. When it starts up, the Application Server reads information from the configuration file and automatically adds JNDI database names to the name space.

J2EE application clients, enterprise beans, and web components are required to have access to a JNDI naming environment.

The application component's naming environment is a mechanism that allows customization of the application component's business logic during deployment or assembly. Use of the application component's environment allows the application component to be customized without the need to access or change the application component's source code.

A J2EE container implements the application component's environment, and provides it 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. The application component provider declares in the deployment descriptor 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 environment naming context available to the application component instances at runtime. The application component's 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.

## Naming References and Binding Information

A resource reference is an element in a deployment descriptor that identifies the component’s coded name for the resource. More specifically, the coded name references a connection factory for the resource. In the example given in the following section, the resource reference name is `jdbc/SavingsAccountDB`.

The JNDI name of a resource and the name of the resource reference 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 de-coupling, if at a later time the component needs to access a different resource, the name does not need to change. This flexibility also makes it easier for you to assemble J2EE applications from preexisting components.

The following table lists JNDI lookups and their associated references for the J2EE resources used by the Application Server.

Table 6–1 JNDI Lookups and Their Associated References

JNDI Lookup Name | Associated 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

# About Custom Resources

- Using Custom Resources

- To create a custom resource

- To edit a custom resource

- To delete a custom resource

- Listing Custom Resources

## Using Custom Resources

A custom resource accesses a local JNDI repository and an external resource accesses an external JNDI repository. Both types of resources need user-specified factory class elements, JNDI name attributes, etc. In this section, we will discuss how to configure JNDI connection factory resources, for J2EE resources, and how to access these resources.

Within the Application Server, you can create, delete, and list resources, as well as `list-jndi-entities`.

## To create a custom resource

1. In the left pane of the Admin Console, open the Application Server instance for the JNDI configuration to be modified.

2. Open the JNDI tab and click Custom Resources.

   If any custom resources have been created already, they are listed in the right pane. To create a new custom resource, click New. Open the JNDI tab and click New. A page for adding a new custom resource appears.

3. In the JNDI Name field, enter the name to use to access the resource.

   This name will be registered in the JNDI naming service.

4. In the Resource Type field, enter a fully qualified type definition, as shown in the example above.

   The Resource Type definition follows the format, `xxx.xxx`.

5. In the Factory Class field, enter a factory class name for the custom resource to be created.

   The Factory Class is the user-specified name for the factory class. This class implements the `javax.naming.spi.ObjectFactory` interface.

6. In the Description field, enter a description for the resource to be creating.

   This description is a string value and can include a maximum of 250 characters.

7. In the Additional Properties section, add the property name and value.

8. Mark the Custom Resource Enabled checkbox, to enable the custom resource.

9. Click OK to save your custom resource.

   If the custom resource is deployed on a cluster or a stand-alone instance, you can manage targets using the Targets tab. The tab appears after the custom resource has been created. Set the target by entering the target name and clicking OK.

##### Equivalent asadmin command

`create-custom-resource`

## To edit a custom resource

1. In the left pane of the Admin Console, open the Application Server instance for the JNDI configuration to be modified.

2. Open JNDI and select Custom Resources.

   If any custom resources have been created already, they are listed in the right pane.

3. Click on the file name in the right pane.

4. Edit the Resource Type field, the Factory Class field, or the Description field.

5. Mark the Custom Resource Enabled checkbox, to enable the custom resource.

6. Click Save to save the changes to the custom resource.

## To delete a custom resource

1. In the left pane of the Admin Console, open the JNDI tab.

2. Click Custom Resources.

   If any custom resources have been created already, they are listed in the right pane.

3. Click in the box next to the name of the resource to be deleted.

4. Click Delete. The custom resource is deleted.

##### Equivalent asadmin command

`delete-custom-resource`

## Listing Custom Resources

To list custom resources, type the `asadmin list-custom-resources` command. For example, to list custom resources on the host `plum`, type the following:

    $asadmin list-custom-resources --host plum target6

For the full context, type `asadmin help list-custom-resources`.

# About External JNDI Repositories and Resources

- Using External JNDI Repositories and Resources

- To create an external resource

- To edit an external resource

- To delete an external resource

- Listing External Resources

## Using External JNDI Repositories and Resources

Often applications running on the Application Server require access to resources stored in an external JNDI repository. For example, generic Java objects could be stored in an LDAP server as per the Java schema. External JNDI resource elements let users configure such external resource repositories. The external JNDI factory must implement `javax.naming.spi.InitialContextFactory` interface.

An example of the use of an external JNDI resource is:

    <resources>
     <!-- external-jndi-resource element specifies how to access J2EE resources
     -- stored in an external JNDI repository. The following 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>

## To create an external resource

1. In the left pane of the Admin Console, open the Application Server instance for the JNDI configuration to be modified.

2. Open JNDI and select External Resources.

   If any external resources have been created already, they are listed in the right pane.

3. To create a new external resource, click New.

4. In the JNDI Name field, enter the name that is to be used to access the resource.

   This name is registered in the JNDI naming service.

5. In the Resource Type field, enter a fully qualified type definition, as shown in the example above.

   The Resource Type definition follows the format, `xxx.xxx`.

6. In the JNDI Lookup field, enter the JNDI value to look up in the external repository.

   For example, when creating an external resource to connect to an external repository, to test a bean class, the JNDI Lookup can look like this: `cn=`testmybean.

7. In the Factory Class field, enter a JNDI factory class external repository, for example, `com.sun.jndi.ldap`.

   This class implements the `javax.naming.spi.ObjectFactory` interface.

8. In the Description field, enter a description for the resource to be created.

   This description is a string value and can include a maximum of 250 characters.

9. In the Additional Properties section, add the property name and value.

10. Mark the External Resource Enabled checkbox, to enable the external resource.

11. Click OK to save the external resource.

    If the external resource is deployed on a cluster or a stand-alone instance, you can manage targets using the Targets tab. The tab appears after the external resource has been created. Set the target by entering the target name and clicking OK.

##### Equivalent asadmin command

`create-jndi-resource`

## To edit an external resource

1. In the left pane of the Admin Console, open the Application Server instance for the JNDI configuration to be modified.

2. Open JNDI and select External Resources.

   If any external resources have been created already, they are listed in the right pane.

3. To edit an external resource, click on the file name in the right pane.

4. Edit the Resource Type field, the JNDI Lookup field, the Factory Class field, or the Description field.

5. Mark the External Resource Enabled checkbox, to enable the external resource.

6. Click Save to save the changes to the external resource.

## To delete an external resource

1. In the left pane of the Admin Console, open the JNDI tab.

2. Click External Resources.

   If any external resources have been created already, they are listed in the right pane.

3. Click the box next to the name of the resource to be deleted.

4. Click Delete. The external resource is deleted.

##### Equivalent asadmin command

`delete-jndi-resource`

## Listing External Resources

To list external resources, type the `asadmin list-jndi-resources` command and specify the JNDI name. For example, to list an external resource, type the following:

`$asadmin list-jndi-resources --user adminuser --host plum jndi_name_test`

For the full context, type `asadmin help list-jndi-resources`.

- Previous: Chapter 5 Configuring JavaMail Resources
- Next: Chapter 7 Connector Resources

- © 2010, Oracle Corporation and/or its affiliates