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
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?
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, available from here
- 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:
-
Stand Alone Installation: %ORACLE_HOME%/bin/oc4j
start
Note that the oc4j command
expects the JAVA_HOME environment variable to point to a full JDK
installation.
-
OracleAS Managed Installation: %ORACLE_HOME%/opmn/bin/opmnctl startall
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:
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:
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:
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
Bookmark
