2 Java Naming and Directory Interface

Example

The following example shows two lines of Java code to use on the server side in a typical Web or EJB application:

Context ctx = new InitialContext();
myEJBHome myhome = 
        (HelloHome) ctx.lookup("java:comp/env/ejb/myEJB");

The first statement creates a new initial context object, using the default environment. The second statement looks up an EJB home interface reference in the JNDI tree of the application. In this case, myEJB might be the name of a session bean that is declared in the web.xml (or orion-web.xml) configuration file, in an <ejb-ref> tag. For example:

<ejb-ref>
  <ejb-ref-name>ejb/myEJB</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>myEjb.HelloHome</home>
  <remote>myEjb.HelloRemote</remote>
</ejb-ref>

This chapter focuses on setting up the initial contexts for using JNDI and describing how OC4J performs JNDI lookups. For more information about the other JNDI classes and methods, see the Javadoc at:

http://java.sun.com/products/jndi/1.2/javadoc/index.html

Environment Properties

If the ORMI protocol is being used, ApplicationClientInitialContextFactory reads the properties listed in Table 2-2 from the environment.

Accessing Objects from an Application Client

This section contains an example of how to configure an application client to access an EJB running inside an OC4J instance in the same location.

First, the EJB is deployed into OC4J. Here are excerpts of the deployment descriptors of the EJB.The EJB is deployed with the name EmployeeBean. The name is defined this way in ejb-jar.xml:

<ejb-jar>
  <display-name>bmpapp</display-name>
  <description>
     An EJB app containing only one Bean Managed Persistence Entity Bean
  </description>
  <enterprise-beans>
     <entity>
        <description>no description</description>
        <display-name>EmployeeBean</display-name>
        <ejb-name>EmployeeBean</ejb-name>
        <home>bmpapp.EmployeeHome</home>
        <remote>bmpapp.Employee</remote>
        <ejb-class>bmpapp.EmployeeBean</ejb-class>
        <persistence-type>Bean</persistence-type>
        ...
     </entity>
  </enterprise-beans>
..
</ejb-jar>

The EJB EmployeeBean is bound to the JNDI location java:comp/env/bmpapp/EmployeeBean in orion-ejb-jar.xml:

orion-ejb-jar.xml file:

<orion-ejb-jar>
   <enterprise-beans>
       <entity-deployment name="EmployeeBean"
           location="bmpapp/EmployeeBean" table="EMP">
                        ...
       </entity-deployment>
                        ...
   </enterprise-beans>
           ...
</orion-ejb-jar>

The application client program uses the EmployeeBean EJB, and refers to it as EmployeeBean. An excerpt from the application client program follows:

public static void main (String args[])
{
 ...
 Context context = new InitialContext();
 /**
  * Look up the EmployeeHome object. The reference is retrieved from the
  * application-local context (java:comp/env). The variable is
  * specified in the assembly descriptor (META-INF/application-client.xml).
  */
 Object homeObject =
     context.lookup("java:comp/env/EmployeeBean");
 // Narrow the reference to an EmployeeHome.
 EmployeeHome home =
     (EmployeeHome) PortableRemoteObject.narrow(homeObject,
                                                EmployeeHome.class);
 // Create a new record and narrow the reference.
 Employee rec =
     (Employee) PortableRemoteObject.narrow(home.create(empNo,
                                                        empName,
                                                        salary),
                                            Employee.class);
 // call method on the EJB
 rec.doSomething();
 ...
}

Note that we are not passing a hash table when creating a context in the line:

Context context = new InitialContext();

This is because the context is created with values read from the jndi.properties file, which in this example contains:

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

Alternatively, you can pass a hash table to the constructor of InitialContext instead of supplying a jndi.properties file. The code looks like this:

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

Because the application client code refers to the EmployeeBean EJB, you must declare this in the <ejb-ref> element in the application-client.xml file:

<application-client>
   <display-name>EmployeeBean</display-name>
   <ejb-ref>
       <ejb-ref-name>EmployeeBean</ejb-ref-name>
       <ejb-ref-type>Entity</ejb-ref-type>
       <home>bmpapp.EmployeeHome</home>
       <remote>bmpapp.Employee</remote>
   </ejb-ref>
</application-client>

Recall that the EmployeeBean EJB is bound to the JNDI location java:comp/env/bmpapp/EmployeeBean as configured in the orion-ejb-jar.xml file. You must map the EJB name used in the application client program to the JNDI location where the EJB is actually bound to. You must do this in the orion-application-client.xml file:

orion-application-client.xml file:
<orion-application-client>
   <ejb-ref-mapping name="EmployeeBean" location="bmpapp/EmployeeBean" />
</orion-application-client>

Objects in the Same Application

You can use J2EE application components to access objects in the same application from servlets, JSP pages, and EJBs.

When code is running in a server, it is, by definition, part of an application. Because the code is part of an application, OC4J can establish defaults for properties that JNDI uses. Application code does not need to provide any property values when constructing a JNDI InitialContext object.

When this context factory is being used, the ApplicationContext is specific to the current application, so all the references specified in files such as web.xml, orion-web.xml, or ejb-jar.xml for that application are available. This means that a lookup using java:comp/env works for any resource that the application has specified. Lookups using this factory are performed locally in the same Java virtual machine (JVM).

If your application must look up a remote reference, such as a resource in another J2EE application in the same JVM or a resource external to any J2EE application, then you must use RMIInitialContextFactory or IIOPInitialContextFactory. See "Objects Not in the Same Application".

<data-source
    class="oracle.jdbc.pool.OracleConnectionCacheImpl"
    location="jdbc/pool/OracleCache"
    username="hr"
    password="hr"
    url="jdbc:oracle:thin:@//<hostname>:<TTC port>/<DB ID>"
/>

<resource-ref>
   <description>
      A data source for the database in which
      the EmployeeService enterprise bean will
      record a log of all transactions.
   </description>
   <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
   <res-auth>Container</res-auth>
   <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

<resource-ref-mapping name="jdbc/EmployeeAppDB" location="jdbc/pool/OracleCache" />

...
try {
  InitialContext ic = new InitialContext();
  ds = (DataSource) ic.lookup("java:comp/env/jdbc/EmployeeAppDB");
  ...
}
catch (NamingException ne) {
  throw new ServletException(ne);
}
...

Objects Not in the Same Application

Use one of the following context factories to access objects not in the same application:

• RMIInitialContextFactory

• IIOPInitialContextFactory

Hashtable env = new Hashtable();
env.put("java.naming.factory.initial",
"com.evermind.server.rmi.RMIInitialContextFactory");
env.put("java.naming.provider.url","ormi://remotehost/bmpapp");
env.put("java.naming.security.principal","SCOTT");
env.put("java.naming.security.credentials","TIGER");
Context context = new InitialContext(env);
Object homeObject =
context.lookup("java:comp/env/EmployeeBean");

<ejb-ref>
<ejb-ref-name>EmployeeBean</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>bmpapp.EmployeeHome</home>
<remote>bmpapp.Employee</remote>
</ejb-ref>

<ejb-ref-mapping name="EmployeeBean" location="bmpapp/EmployeeBean" />

Multiple Islands on a Given Subnet

Although OC4J processes can be organized into groups (known as islands) to improve state-replication performance, EJB applications replicate state between all OC4J processes in the OC4J instance and do not use the island subgrouping. This is described in the clustering chapter in the Oracle Application Server Containers for J2EE User's Guide.

Consequently, JNDI clustering is not limited to an island subnet. If there are multiple islands on a single subnet, then all islands on that subnet share the global JNDI context.

Propagating Changes Across the Cluster

Rebinding (renaming) and unbinding are not propagated: they apply locally but are not shared across the cluster.

Bindings to values that are not serializable are also not propagated across the cluster.

Binding a Remote Object

If you bind a remote object (typically a home or EJB object) in an application context, then that JNDI object is shared across the cluster but there is a single point of failure if the first server it is bound to fails.

JNDI Lookups in a Multiple-Instance Environment

In an environment with multiple OC4J instances, JNDI lookups require additional information:

• opmn prefix

• ons host name

• ons port number

This applies to EJBs and JMS, as well.