How-To Configure and Use JNDI in Oracle
Container for Java EE 11 Technology Preview
First Created: 01-Nov-2004
Last Updated: 12-April-2007
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 Java EE 11 Technology
Preview, standalone version, with a web site configured
(example http-web-site)
- Sun's JDK 1.5.0 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 Container for Java EE 11 Technology Preview.
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 10g, 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 11 Technology Preview instance
as follows:
o
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.
o
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
