How-To Configure and Use JNDI in OC4J 10g (10.1.3)

First Created: 01-Nov-2004
Last Updated: 16-Jan-2006
Author: Frances Zhao

• Introduction
• What are the Prerequisites?
  • What Should You Know?
  • What are the Software Requirements?
  • What are the Notations?
• How to Build the Application?
  • Creating a Simple Session Bean
  • Creating an Initial Context Using Hashtable
  • Creating an InitialContext Using jndi.properties
  • JNDI Lookup
• How to Run the Application?
  • Examining the How to Distribution
  • Setting up the Application
  • Running an OC4J Instance
  • Generating, Compiling and Deploying the Application
  • Running the Application
• Summary

Introduction

This demo illustrates two ways of InitialContext creation in J2EE application clients, and the basic JNDI lookup in OC4J:

• Using Hashtable as parameter to constructor
• Using jndi.properties file

When an application client must look up a resource that is available in a J2EE server application, the client uses ApplicationClientInitialContextFactory in the com.evermind.server package to construct the initial context.

There are some environment properties that ApplicationClientInitialContextFactory needs. These can be specified in the client code, or can be specified in the jndi.properties file that is part of the application's JAR file that is included in the EAR file.

 

What are the Prerequisites?

What you should know?

• You should be familiar with these technologies: EJB;
• Link to other OC4J Howto's on OTN

What are the Software Requirements?

This demo requires that the following sofware components are installed and configured correctly:

• Oracle Containers for J2EE 10g (10.1.3) , standalone version, with a web site configured (example http-web-site)
• Sun's JDK 1.4.1 or above
• Apache Ant 1.6.2 or above, to build the application, available from here
• Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

What are the Notations?

• %ORACLE_HOME% - The directory where you installed OC4J.
• %JAVA_HOME% - The directory where your JDK is installed
• %HOWTO_HOME% - The directory where this demo is unzipped

How to Build the Application?

Creating a Simple Session Bean

For the purpose of this How-to, a simple session bean is created, to be looked up from the application client. This session bean implements a very simple Stack, which offers 3 external operations: push, pop, and display of the stack contents as a string. The implementation simply wraps around a java.util.Stack object. The code is under: %HOWTO_HOME%/src/ejb/bean.

Creating an Initial Context Using Hashtable

The first way to create an InitialContext is to use the parameterized constructor InitialContext(Hashtable). In the client code of this How-to, we used:

Hashtable env = new Hashtable();
env.put("java.naming.factory.initial",
  "com.evermind.server.ApplicationClientInitialContextFactory");
env.put("java.naming.provider.url","ormi://localhost/jndidemo");
env.put("java.naming.security.principal","SCOTT");
env.put("java.naming.security.credentials","TIGER");
Context initial = new InitialContext(env);

Creating an InitialContext Using jndi.properties

Alternatively, the initial context can be created based on a file called "jndi.properties" that is bundled with the J2EE application's EAR file. For this How-to, this file looks like:

java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory
java.naming.provider.url=ormi://localhost/jndidemo
java.naming.security.principal=SCOTT
java.naming.security.credentials=TIGER

Note: In both ways of creating an InitialContext, if you are going to run this how-to within an OracleAS environment (as opposed to using a standalone OC4J), you need to modify the "java.naming.provider.url" to use the "opmn:ormi:" protocol prefix, instead of simply "ormi:". The modification should be for both jndi.properties and DemoClient.java. This allows a client to attempt a lookup without hard-coding the ORMI port information (by default 23791). OC4J JNDI will contact the OPMN process to determine the proper ORMI port to use for the OracleAS environment. For example, use "java.naming.provider.url=opmn:ormi://hostname/jndidemo" instead of "java.naming.provider.url=ormi://hostname/jndidemo".

JNDI Lookup

Once the initial context is created, you can look up a desired object like the following. This is an EJB home object. The lookup name is specified in application-client.xml, and the reference would be retrieved from the application-local context (i.e., java:comp/env).

Object homeObject =
  context.lookup("java:comp/env/SimpleStackBean");

Here is the application-client.xml part that defined the lookup name:

<ejb-ref>
  <ejb-ref-name>SimpleStackBean</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>jndidemo.SimpleStackHome</home>
  <remote>jndidemo.SimpleStack</remote>
</ejb-ref>

In this How-to, we have used the JNDI location "jndidemo/SimpleStackBean" for the stack bean, as defined in orion-ejb-jar.xml. Therefore, we also need an orion-application-client.xml file that defines the mapping from the above name "SimpleStackBean" to this real JNDI location. Like:

<orion-application-client>
  <ejb-ref-mapping name="SimpleStackBean" location="jndidemo/SimpleStackBean" />
</orion-application-client>

How to Run the Application?

The following instructions are for running this demonstration on a standalone instance of Oracle Containers for J2EE 10g (10.1.3).

Examining the How to Distribution

• build - temporary directory created during the build
• log - temporary directory holding build/deploy logs
• etc - all necessary files to package the application
• lib - holds the application archives that could be deployed (e.g., ear, war, rar, jar files)
• doc - the How-to document and Javadoc's
• • javadoc - the javadoc of the different source files
  • how-to.html - this How-to page
• src - the source of the demo
  • ejb - contains Java code for the EJB and the client used

Setting Up the Application

Environment Configuration

Please check to make sure that the following properties are configured correctly in the ant-oracle.properties file located in the root of the sample's distribution (NOTE:  Some of these properties will default to the values of corresponding environment variables as noted below.  If you have these variables setup in your environment you may not have to alter the values in the file).  If necessary, modify these variable to the proper values for you environment:

• oracle.home - the root directory of oracle installation.  Defaults to ORACLE_HOME environment variable.
• java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
• oracleas.host - the hostname of the platform on which the OC4J instance is running.  Defaults to localhost.
• oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
• oracleas.admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.admin.password - the password for the OC4J administrator.  Defaults to " welcome".
• oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to " default-web-site".

In addition, please make sure that the ant command associated with the OC4J ant distribution is in your execution path ( %ORACLE_HOME%/ant/bin).

Configuring the Environment for a Managed OracleAS Instance

If you are running a managed version of the Oracle Application Server 10 g, you are using OPMN, you must change the following values to match your configuration:

• oracleas.http.port - the port on which the Oracle HTTP Server (OHS) is listening.
• oracleas.admin.port  - The OPMN request port, as specified in opmn.xml, the default value is 6003.  You can also check the OPMN request port using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.deployer.uri - the URI to use to do the different administration operation (deployment, undeployment). The file contains different URI depending of the topology of your application: stand alone OC4J, Managed Single Node or Managed Cluster. You just need to un-comment the URI that matches your toplogy.
• oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed.

Starting the OC4J Instance

Start an OracleAS 10 g (10.1.3) instance as follows:

Generating, Compiling and Deploying the Application

Build the Application

Make sure that the ant command associated with the OC4J ant distribution is in your execution path ( %ORACLE_HOME%/ant/bin).

In the top-level %HOWTO_HOME% directory, type the command:

• ant

You should now have newly created servlet_demo.ear in your %HOWTO_HOME%/dist directory.

This command would also attempt to deploy the application if the build is successful. It will first test whether OC4J is running.

Deploy the Application

You can also deploy the application separately by using the following command. Make sure the %ORACLE_HOME% environment variable is defined. In the top-level %HOWTO_HOME% directory, type the command:

• ant deploy

Running the Application

There is another target in the build.xml, called "run". Make sure the application is successfully built and deployed, and in the top-level %HOWTO_HOME% directory, simply type the command:

• ant run

You should be able to see two successful InitialContext creations and lookups, followed by continuous dumps of the stack content as output.

Summary

In this document, you should have:

• Learned how to create InitialContext using ApplicationClientInitialContextFactory from application clients
• Learned how to perform basic JNDI lookups