Java TM External JNDI Resource Factory Sample Application

  Samples Index



External JNDI Resource Factory Sample Application

This document describes how to create an application that requires access to an external JNDI resource factory in the Sun Java System Application Server 8.1 2005Q1.

This document contains the following sections:



Overview

The External JNDI Resource Factory sample application demonstrates:

The external JNDI resource factory used in this application is an LDAP based object repository that allows the storage and retrieval of objects in a given LDAP server.

Along with the external JNDI resource factory or repository, the sample application provides an application client component that illustrates how to access such a resource factory.


The Sample Application

The External JNDI Resource Factory sample application contains an application client that illustrates how to access the external JNDI resource factory. To facilitate the testing, the application client provides an option to create and place the external factory in a remote LDAP server as well as options to store and retrieve objects from such a factory.

The directory structure of the sample application is as follows (all paths are relative to <install_dir>/samples/jndi/apps/external/:

external-client/src/conf - contains the application client deployment descriptors required for deployment on the Application Server.
external-client/src/java/samples/jndi/external/client - contains the source code for the application client.
external-share/src/java/samples/jndi/external/share - contains the source code for the ExternalBean (added for testing purposes). The application client allows adding this kind of objects into the external repository so that one can extract them later for verification purposes. This directory also contains the classes that implement the external JNDI resource factory: the interface of the external factory (ExternalRepository), its implementation (ExternalFactoryImpl), and the factory object required to create such objects (ExternalFactoryImplFactory).


Compiling and Assembling the Application



This section contains instructions on how to build and assemble the application.

  1. Compile and assemble the application.
    1. Change directory to: <install_dir>/samples/jndi/apps/external.
    2. Execute the command asant core. This command compiles all sources and assembles the following module:
      • jndi-external.ear
      • Main application, containing an application client component that illustrates how to use the external JNDI resource factory

  2. Deploy the application.
  3. After compiling the sources and assembling the EAR file, you may proceed to Deploying the Sample Application. Steps 3 and 4 are optional.
  4. Clean the application project area (optional).
  5. Execute the command asant clean to remove all the files generated in Step 1.
  6. Generate API documentation (optional).
  7. Execute the command asant javadocs under <install_dir>/samples/jndi/apps/external. The API documentation will be located under <install_dir>/samples/jndi/apps/external/javadocs.


Deploying the Sample Application

This section contains instructions on how to deploy the application on the Application Server.

Execute the command asant deploy under <install_dir>/samples/jndi/apps/external. This command deploys the EAR file of the External JNDI Resource Factory sample application: jndi-external.ear.


Verifying Deployment

As an optional step, you can use the asadmin command to verify that the application has been registered. Otherwise, proceed directly to Running the Sample Application.

To verify the registration of the application, execute the command asadmin list-components to look at applications deployed with a server instance. For example:

<install_dir>/bin/asadmin list-components --user <username> --password <password>

You will see the sample external JNDI resource factory listed as a J2EE application:

jndi-external <j2ee-application>

Running the Sample Application


Note

This application requires access to an LDAP server. Before running the application client, a property file, containing the required property to access the LDAP server, must be created. This property file can be placed in a local directory accessible to the application client, or in a Web server where it can be accessed via its URL. To create this file, you can copy and modify the file src/conf/ExternalRepository.properties. There are three properties in this file. You must set the java.naming.provider.url property to indicate where your own LDAP server is running. You may change the external.repository.name property if you wish to change the name of the external repository.


Execute the command asant run under <install_dir>/samples/jndi/apps/external.

This command invokes the application client of the External JNDI Resource Factory sample application. The application client requires at least two arguments: PropertyFileLocation and Command. The property file can be a local file or URL. The Command can be either CREATE, STORE, or LOOKUP. CREATE binds the external resource factory in the LDAP server indicated in the property file. STORE and LOOKUP, as their names indicate, store and retrieve objects from the external repository. The run target of the main build.xml file has been configured to use four properties that can be set appropriately to run either of the three options. These properties are property.file.location, command.name, command.arg1, and command.arg2. For example, to create the external repository in the remote LDAP server, use the following command:

asant -Dproperty.file.location="URL_or_pathname_of_property_file" -Dcommand.name="CREATE" run

To store an object in the external repository, use the following command:

asant -Dproperty.file.location="URL_or_pathname_of_property_file" -Dcommand.name="STORE" -Dcommand.arg1="object_jndi_name" -Dcommand.arg2="object_type" run

To look up an object in the external repository, use the following command:

asant -Dproperty.file.location="URL_or_pathname_of_property_file" -Dcommand.name="LOOKUP" -Dcommand.arg1="object_jndi_name" run


Troubleshooting

If you encounter problems when running the application, review the Application Server log file located at

<install_dir>/domains/<domain-name>/logs/server.log

to learn what exactly went wrong.


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

Last Updated August 2, 2004