2 How to Access EJBs

Steps for Accessing Any EJB

To access an EJB from a client, you must do the following:

1. If you are remote, download the oc4j.jar file.

2. Set up JNDI properties for the connection, if necessary.

3. Determine which InitialContextFactory you will use for the connection.

4. Retrieve an EJB using either the JNDI name or an EJB reference, which is configured in the deployment descriptor.

These subjects are discussed in the following sections:

• Client Installation of OC4J.JAR

• Setting JNDI Properties

• When Do You Use the Different Initial Context Factory Classes?

• How to Lookup the EJB Reference

• Configuring the EJB Reference Information

• Example of How a Client Invokes an EJB

//Get the Initial Context for the JNDI lookup for a local EJB
InitialContext ic = new InitialContext();
//Retrieve the Home interface using JNDI lookup
Object helloObject = ic.lookup("java:comp/env/ejb/HelloBean");

java.naming.factory.initial=     	com.evermind.server.ApplicationClientInitialContextFactory

java.naming.provider.url=   opmn:ormi://<opmn_host>:<opmn_port>:<oc4j_instance>/<application-name>

java.naming.security.principal=<username>
java.naming.security.credentials=<password>

Hashtable env = new Hashtable(); 
env.put("java.naming.provider.url",
       "opmn:ormi://opmnhost:oc4j_inst1/ejbsamples"); 
env.put("java.naming.factory.initial", 
      "com.evermind.server.ApplicationClientInitialContextFactory"); 
env.put(Context.SECURITY_PRINCIPAL, "guest"); 
env.put(Context.SECURITY_CREDENTIALS, "welcome"); 
Context ic = new InitialContext (env); 
Object homeObject = ic.lookup("java:comp/env/ejb/HelloBean");

// Narrow the reference to a HelloHome.
HelloHome empHome =
	 (HelloHome) PortableRemoteObject.narrow(homeObject,
                                                   HelloHome.class);

java.naming.provider.url=ormi://<hostname>/<application-name>

java.naming.provider.url=ormi://<hostname>:23791/<application-name>\

java.naming.security.principal=<username>
java.naming.security.credentials=<password>

Hashtable env = new Hashtable(); 
env.put("java.naming.provider.url", "ormi://myhost/ejbsamples"); 
env.put("java.naming.factory.initial", 
       "com.evermind.server.ApplicationClientInitialContextFactory"); 
env.put(Context.SECURITY_PRINCIPAL, "guest"); 
env.put(Context.SECURITY_CREDENTIALS, "welcome"); 
Context ic = new InitialContext (env); 
Object homeObject = ic.lookup("java:comp/env/ejb/HelloBean");
  
// Narrow the reference to a HelloHome.
HelloHome helloHome =
  (HelloHome) PortableRemoteObject.narrow(homeObject,
                                                    HelloHome.class);

env.put("java.naming.factory.initial", 
      "com.evermind.server.ApplicationClientInitialContextFactory"); 

InitialContext ic = new InitialContext();

java.naming.factory.initial=
           com.evermind.server.rmi.RMIInitialContextFactory
java.naming.provider.url=opmn:ormi://myserver:oc4j_inst/applname
java.naming.security.principal=admin
java.naming.security.credentials=welcome
dedicated.rmicontext=true

<ejb-ref>
     <ejb-ref-name>ejb/HelloBean</ejb-ref-name>
     <ejb-ref-type>Session</ejb-ref-type>
     <home>hello.HelloHome</home>
     <remote>hello.Hello</remote>
</ejb-ref>

<ejb-ref>
	<ejb-ref-name>ejb/HelloBean</ejb-ref-name>
	<ejb-ref-type>Session</ejb-ref-type>
	<local-home>hello.HelloLocalHome</local-home>
	<local>hello.HelloLocal</local>
</ejb-ref>

Example of How a Client Invokes an EJB

All EJB clients implement the following steps to instantiate a bean, invoke its methods, and destroy the bean:

1. Look up the home interface through a JNDI lookup. Follow JNDI and the EJB specification conventions for retrieving the bean reference, including setting up JNDI properties if the bean is remote to the client. See "How to Lookup the EJB Reference".

2. Narrow the returned object from the JNDI lookup to the home interface, as follows:

   1. When accessing the remote interface, use the PortableRemoteObject.narrow method to narrow the returned object.

   2. When accessing the local interface, cast the returned object with the local home interface type.

3. Create instances of the bean in the server through the returned object. Invoking the create method on the home interface causes a new bean to be instantiated and returns a bean reference.

   
   

   Note: For entity beans that are already instantiated, you can retrieve the bean reference through one of its finder methods.

   
   

4. Invoke business methods, which are defined in the component (remote or local) interface.

5. After you are finished, invoke the remove method. This will either remove the bean instance or return it to a pool. The container controls how to act on the remove method.

These steps are demonstrated in Example 2-2.

package hello;

import javax.servlet.http.*;
import javax.servlet.*;
import javax.ejb.*;
import javax.naming.*;
import java.io.IOException;

public class HelloServlet extends HttpServlet
{
  HelloLocalHome helloHome;
  HelloLocal hello;

  public void init() throws ServletException
  {
    try {
     // 1. Retreive the Home Interface using a JNDI Lookup
     // Retrieve the initial context for JNDI.       // No properties needed when local
      Context context = new InitialContext();

      // Retrieve the home interface using a JNDI lookup using
      // the java:comp/env bean environment variable        // specified in web.xml
      helloHome = (HelloLocalHome)              context.lookup("java:comp/env/ejb/HelloBean");

     //2. Narrow the returned object to be an HelloHome object.      // Since the client is local, cast it to the correct object type.
     //3. Create the local Hello bean instance, return the reference 
      hello = (HelloLocal)helloHome.create();

    } catch(NamingException e) {
      throw new ServletException("Error looking up home", e);
    } catch(CreateException e) {
      throw new ServletException("Error creating local hello bean", e);
    }
  }

  public void doGet(HttpServletRequest request,                        HttpServletResponse response)
    throws ServletException, IOException
  {
    response.setContentType("text/html");
    ServletOutputStream out = response.getOutputStream();
    try
    {
      out.println("<html>");
      out.println("<body>");
     //4. Invoke a business method on the local interface reference.
      out.println(hello.sayHello("James Earl"));
      out.println("</body>");
      out.println("</html>");
    } catch(EJBException e) {
      out.println("EJBException error: " + e.getMessage());
    } catch(IOException e) {
      out.println("IOException error: " + e.getMessage());
    } finally {
      out.close();
    }
  }
}

The jndi.properties file for this client is as follows:

java.naming.factory.initial=         com.evermind.server.ApplicationClientInitialContextFactory
java.naming.provider.url=opmn:ormi://opmnhost:oc4j_inst1/helloworld
java.naming.security.principal=admin
java.naming.security.credentials=welcome

The pure Java client that invokes Hello remotely is as follows:

package hello;

import javax.ejb.*;
import javax.naming.*;
import javax.rmi.PortableRemoteObject;
import java.io.*;
import java.util.*;
import java.rmi.RemoteException;

/*
 * A simple client for accessing an EJB.
 */

public class HelloClient
{
  public static void main(String[] args)
  {
    System.out.println("client started...");
    try {
      // Initial context properties are set in the jndi.properties file
      //1. Retrieve remote interface using a JNDI lookup*/
      Context context = new InitialContext();

     // Lookup the HelloHome object. The reference is retrieved from the
     // application-local context (java:comp/env). The variable is
     // specified in the application-client.xml).
      Object homeObject = context.lookup("java:comp/env/Helloworld");

     //2. Narrow the reference to HelloHome. Since this is a remote       //   object, use the PortableRemoteObject.narrow method.
      HelloHome home = (HelloHome) PortableRemoteObject.narrow                                         (homeObject, HelloHome.class);

     //3. Create the remote object and narrow the reference to Hello.
      Hello remote =
        (Hello) PortableRemoteObject.narrow(home.create(), Hello.class);

     //4. Invoke a business method on the remote interface reference.
      System.out.println(remote.sayHello("James Earl"));

    } catch(NamingException e) {
      System.err.println("NamingException: " + e.getMessage());
    } catch(RemoteException e) {
      System.err.println("RemoteException: " + e.getMessage());
    } catch(CreateException e) {
      System.err.println("FinderException: " + e.getMessage());
    }
  }
}

Accessing an EJB in a Remote Server

A multi-tier situation exists when you have the servlets executing in one server which are to connect and communicate with EJBs in another server. Both the servlets and EJBs are contained in the same application. When you deploy the application to two different servers, the servlets normally look for the local EJB first.

In Figure 2-1, the HelloBean application is deployed to both server 1 and 2. In order to ensure that the servlets only call out from server 1 to the EJBs in server 2, you must set the remote attribute appropriately in the application before deploying on both servers.

Figure 2-1 Multi-Tier Example

Description of the illustration o_1046.gif

The remote attribute in the <ejb-module> element in orion-application.xml for the EJB module denotes whether the EJBs for this application are deployed or not.

1. In server 1, you must set remote=true in the <ejb-module> element of the orion-application.xml file and then deploy the application. The EJB module within the application will not be deployed. Thus, the servlets will not look for the EJBs locally, but will go out to the remote server for the EJB requests.

2. In server 2, you must set remote=false in the <ejb-module> element of the orion-application.xml file and then deploy the application. The application, including the EJB module, is deployed as normal. The default for the remote attribute is false; thus, simply ensure that the remote attribute is not true and redeploy the application.

3. In the <server> element of the rmi.xml file of server 1, configure the location of server 2, which is the remote server. Provide the hostname, port number, username, and password of the remote server, as follows:

   <server host=<remote_host> port=<remote_port> username=<username> password=<password> />
   
   

If multiple remote servers are configured, the OC4J container searches all remote servers for the intended EJB application.

• The INITIAL_CONTEXT_FACTORY is initialized to a RMIInitialContextFactory.

• Instead of creating a new InitialContext, it is retrieved.

• The actual JNDI name is used in the lookup.

• The remote location URL is opmn:ormi://host:oc4j_inst/application. The OPMN port number uses the default and is omitted.

Hashtable env = new Hashtable();
env.put(Context.PROVIDER_URL, "opmn:ormi://theirhost:oc4j_inst/myapp");
env.put(Context.SECURITY_PRINCIPAL, "admin");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
env.put(Context.INITIAL_CONTEXT_FACTORY,
	"com.evermind.server.rmi.RMIInitialContextFactory");

Context ic =  	new com.evermind.server.rmi.RMIInitialContextFactory(). 		getInitialContext(env);

Object homeObject = ic.lookup("ejb/HelloBean");

// Narrow the reference to a HelloHome.
HelloHome helloHome =
	 (HelloHome) PortableRemoteObject.narrow(homeObject,
                                                   HelloHome.class);

Accessing an EJB in Another Application

Normally, you cannot have EJBs communicating across EAR files, that is, across applications that are deployed in separate EAR files. The only way for an EJB to access an EJB that was deployed in a separate EAR file is to declare it to be the parent of the client. Only children can invoke methods in a parent.

For example, there are two EJBs, each deployed within their EAR file, called sales and inventory, where the sales EJB needs to invoke the inventory EJB to check to see if enough widgets are available. Unless the sales EJB defines the inventory EJB to be its parent, the sales EJB cannot invoke any mehtods in the inventory EJB, because they are both deployed in separate EAR files. So, define the inventory EJB to be the parent of the sales EJB and the sales EJB can now invoke any method in its parent.

You can only define the parent during deployment with the deployment wizard. See the "Deploying Applications" section in the "Configuration and Deployment" chapter in Oracle Application Server Containers for J2EE User's Guide on how to define the parent application of a bean. For broader issues on how to package your classes for method invocation, see "Directory Structure Recommendations for EJB Development".

JAAS Support for EJBs

If you invoke any EJB from an application client outside the EJB container, then Java Authentication and Authorization Service (JAAS) is not supported for the EJB. However, if you call the EJB from a servlet within the OC4J instance, then JAAS is supported.

Using the RIMInitialContextFactory Object

If you access an EJB in an application from an EJB in a different application, then you cannot use the RMIInitialContextFactory object. In this scenario, you must use a parent-child relationship between these applications, and you must use the default initial context factory object.

Recovering From Deadlock Conditions

If the call sequence of several beans cause a deadlock scenario, the OC4J container notices the deadlock condition and throws a Remote exception that details the deadlock condition in one of the offending beans.

Recovering From a NamingException While Accessing a Remote EJB

If you are trying to remotely access an EJB and you receive an javax.naming.NamingException error, your JNDI properties are probably not initialized properly.

Recovering From NullPointerException While Accessing a Remote EJB

When accessing a remote EJB from a Web application, you receive the following error: "java.lang.NullPointerException: domain was null ". In this case, you must set an environment property in your client while accessing the EJB set dedicated.rmicontext to true.

The following demonstrates how to use this additional environment property:

Hashtable env = new Hashtable( );
env.put (Context.INITIAL_CONTEXT_FACTORY,
    "com.evermind.server.rmi.RMIInitialContextFactory");
env.put (Context.SECURITY_PRINCIPAL, "admin");
env.put (Context.SECURITY_CREDENTIALS, "admin");
env.put (Context.PROVIDER_URL, "ormi://myhost-us/ejbsamples");
env.put ("dedicated.rmicontext", "true"); // for 9.0.2.1 and above
Context context = new InitialContext (env);

See "Load Balancing Options" for more information on dedicated.rmicontext.