2
An EJB Primer For OC4J

After you have installed OC4J and configured the base server and default Web site, you can start developing J2EE applications. This chapter assumes that you have a working familiarity with simple J2EE concepts and a basic understanding for EJB development.

This chapter demonstrates simple EJB development with a basic OC4J-specific configuration and deployment. Download the stateless session bean example (stateless.jar) from the OC4J sample code page on the OTN site.

Developing and deploying EJB applications with OC4J includes the following:

• Develop EJBs--Developing and testing an EJB module within the standard J2EE specification.

• Prepare the EJB Application for Assembly--Before deploying, you must modify an XML file that acts as a manifest file for the enterprise application.

• Deploy the Enterprise Application to OC4J--Archive the enterprise Java application into an Enterprise ARchive (EAR) file and deploy it to OC4J.

Develop EJBs

The development of EJB components for the OC4J environment is identical to development in any other standard J2EE environment. The steps for developing EJBs are as follows:

1. Create the Development Directory--Create a development directory for the enterprise application (as shown in Figure 2-1).

2. Implement the Enterprise JavaBeans--Develop your EJB with its home interface, remote interface, and bean implementation.

3. Create the Deployment Descriptor--Create the standard J2EE EJB deployment descriptor for all beans in your EJB application.

4. Archive the EJB Application--Archive your EJB files into a JAR file.

Create the Development Directory

You can develop your application in any manner. We encourage you to use consistent naming for locating your application easily. One method would be to implement your enterprise Java application under a single parent directory structure, separating each module of the application into their own sub-directories.

Our employee example was developed using the directory structure mentioned in the OC4J User's Guide. Notice in Figure 2-1 that the EJB and Web modules exist under the employee application parent directory and are developed separately in their own directory.

Figure 2-1 Employee Directory Structure

Text description of the illustration primera.gif

Note: For EJB modules, the top of the module (ejb_module) represents the start of a search path for classes. As a result, classes belonging to packages are expected to be located in a nested directory structure beneath this point. For example, a reference to a package class 'myapp.Employee.class' is expected to be located in "...employee/ejb_module/myapp/Employee.class".

Implement the Enterprise JavaBeans

When you implement an EJB, create the following:

1. A home interface for the bean. The home interface extends javax.ejb.EJBHome. It defines the create method for your bean. If the bean is an entity bean, it also defines the finder method(s) for that bean.

2. A remote interface for the bean. The remote interface declares the methods that a client can invoke. It extends javax.ejb.EJBObject.

3. The bean implementation that includes the following:
   1. the implementation of the business methods that are declared in the remote interface

   2. the container callback methods that are inherited from either the javax.ejb.SessionBean or javax.ejb.EntityBean interfaces

   3. the ejbCreate method with parameters matching those of the create method as defined in the home interface

Creating the Home Interface

The home interface is used to create and destroy the bean instance; thus, it defines the create method for your bean. Each type of EJB can define the create method in the following ways:

EJB Type	Create Parameters
Stateless Session Bean	Can have only a single create method, with no parameters.
Stateful Session Bean	One or more create methods, each with its own defined parameters.
Entity Bean	Zero or more create methods, each with its own defined parameters. All entity beans must define one or more finder methods, where at least one is a findByPrimaryKey method.

For each create method, a corresponding ejbCreate method is defined in the bean implementation. The client invokes the create method that is declared within the home interface. The container turns around and calls the ejbCreate method--with the appropriate parameter signature--within your bean implementation. You can use the parameter arguments to initialize the state of the new EJB object.

1. The home interface must extend the javax.ejb.EJBHome interface.

2. All create methods must throw the following exceptions:
   • javax.ejb.CreateException

   • either java.rmi.RemoteException or javax.ejb.EJBException

Example

The following code sample shows a home interface for a session bean called EmployeeHome.

package employee;

import javax.ejb.*;
import java.rmi.*;

public interface EmployeeHome extends EJBHome
{
  public Employee create()
    throws CreateException, RemoteException;
}

Creating the Remote Interface

The remote interface defines the business methods of the bean that the client can invoke.

1. The remote interface of the bean must extend the javax.ejb.EJBObject interface and its methods must throw the java.rmi.RemoteException exception.

2. You must declare the remote interface and its methods as public, because clients that invoke these methods are remote.

3. The remote interface, all its method parameters, and return types must be serializable. In general, any object that is passed between the client and the EJB must be serializable, because RMI marshals and unmarshals the object on both ends.

4. Any exception can be thrown to the client, as long as it is serializable. Runtime exceptions, including EJBException and RemoteException, are transferred back to the client as remote runtime exceptions.

Example

The following code sample shows a remote interface called Employee with its defined methods, each of which will be implemented in the stateless session bean.

package employee;

import javax.ejb.*;
import java.rmi.*;
import java.util.*;

public interface Employee extends EJBObject
{
  public Collection getEmployees()
    throws RemoteException;

  public EmpRecord getEmployee(Integer empNo)
    throws RemoteException;

  public void setEmployee(Integer empNo, String empName, Float salary)
    throws RemoteException;

  public EmpRecord addEmployee(Integer empNo, String empName,

	Float salary)
    throws RemoteException;

  public void removeEmployee(Integer empNo)
    throws RemoteException;
}

Implementing the Bean

The bean contains the business logic for your application. It implements the following methods:

1. The bean methods defined in the remote interface. The signature for each of these methods must match the signature in the remote interface.

   The bean in the example application consists of one class, EmployeeBean, that retrieves an employee's information.

2. The methods defined in the home interface are inherited from the SessionBean or EntityBean interface. The container uses these methods for controlling the life cycle of the bean. These include the ejb<Action> methods, such as ejbActivate, ejbPassivate, and so on.

3. The ejbCreate methods that correspond to the create method(s) that are declared in the home interface. The container invokes the appropriate ejbCreate method when the client invokes the corresponding create method.

4. Any methods that are private to the bean or package used for facilitating the business logic. This includes private methods that your public methods use for completing the tasks requested of them.

Accessing the Bean

All EJB clients--including standalone clients, servlets, JSPs, and JavaBeans--perform the following steps to instantiate a bean, invoke its methods, and destroy the bean:

1. Look up the bean home interface through a JNDI lookup, which is used for the life cycle management. Follow JNDI conventions for retrieving the bean reference, including setting up JNDI properties if the bean is remote to the client.

2. Narrow the returned object from the JNDI lookup to the home interface through the PortableRemoteObject.narrow method.

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

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

4. Invoke business methods that are defined in the remote interface.

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

Example

The following example is executed from a servlet, which can also be executed from a JSP or JavaBean, that is co-located in the same container with the stateless session bean. Thus, the JNDI lookup does not require JNDI properties, such as the factory, location, or security parameters.

Note: The JNDI name is specified in the <ejb-ref> element in the EJB client XML configuration file--in this case, the servlet web.xml file--as follows: <ejb-ref> <ejb-ref-name>EmployeeBean</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>employee.EmployeeHome</home> <remote>employee.Employee</remote> </ejb-ref>

This code should be executed within a TRY block for catching errors, but the TRY block was removed to show the logic clearly. See the downloadable example for the full exception coverage.

public class EmployeeServlet extends HttpServlet
{
  EmployeeHome home;
  Employee empBean;

  public void init() throws ServletException
  {
    //Retrieve the initial context for JNDI
    Context context = new InitialContext();

    //Retrieve the home interface using a JNDI lookup using
    // the java:comp/env bean environment variable specified in web.xml
    Object homeObject =
                 context.lookup("java:comp/env/EmployeeBean");
    
    //Narrow the returned object to be an EmployeeHome object
    home =
        (EmployeeHome) PortableRemoteObject.narrow(homeObject,
                                                   EmployeeHome.class);

    // Create the remote Employee bean instance and return a reference 
    // to the remote interface to this bean.
    empBean =
        (Employee) PortableRemoteObject.narrow(home.create(), Employee.class);
  }
  
  public void doGet(HttpServletRequest request,
                        HttpServletResponse response)
          throws ServletException, IOException
  {
    response.setContentType("text/html");
    ServletOutputStream out = response.getOutputStream();

    //Invoke a method on the remote interface reference.
    Collection emps = empBean.getEmployees();

    out.println("<html>");
    out.println(	"<head><title>Employee Bean</title></head>");
    out.println(	"<body>");
    out.println(		"<table border='2'>");
    out.println(			"<tr><td>" + "<b>EmployeeNo</b>"
                + "</td><td>"    + "<b>EmployeeName</b>"
                + "</td><td>"    + "<b>Salary</b>"
                + "</td></tr>");

    Iterator iterator = emps.iterator();

    while(iterator.hasNext()) {
        EmpRecord emp = (EmpRecord)iterator.next();
        out.println(			"<tr><td>" + emp.getEmpNo()
                    + "</td><td>"    + emp.getEmpName()
                    + "</td><td>"    + emp.getSalary()
                    + "</td></tr>");
    }

    out.println(		"</table>");
    out.println(	"</body>");
    out.println("</html>");
    out.close();
 }
}

Create the Deployment Descriptor

After implementing and compiling your classes, you must create the standard J2EE EJB deployment descriptor for all beans in the module. The XML deployment descriptor (defined in the ejb-jar.xml file) describes the application components and provides additional information to enable the container to manage the application. The structure for this file is mandated in the DTD file, which is provided at http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd.

The following example shows the sections that are necessary for the Employee example.

Example 2-1 XML Deployment Descriptor for Employee Bean

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise 
JavaBeans 1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">

<ejb-jar>
   <enterprise-beans>
      <session>
         <description>Session Bean Employee Example</description>
         <ejb-name>EmployeeBean</ejb-name>
         <home>employee.EmployeeHome</home>
         <remote>employee.Employee</remote>
         <ejb-class>employee.EmployeeBean</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Bean</transaction-type>
      </session>
   </enterprise-beans>
</ejb-jar>

Archive the EJB Application

Once you have finalized your implementation and have created the deployment descriptors, archive your EJB application into a JAR file. The JAR file should include all EJB application files and the deployment descriptor.

Note: If you have included a Web application as part of this enterprise Java application, follow the instructions for building the Web application in the Oracle9iAS Containers for J2EE User's Guide. Then, modify the *-web-site.xml file, and archive all Web application files into a WAR file.

For example, to archive your compiled EJB class files and XML files for the Employee example into a JAR file, perform the following in the ../employee/ejb_module directory:

% jar cvf Employee-ejb.jar .

This archives all files contained within the ejb_module subdirectory within the JAR file.

Prepare the EJB Application for Assembly

Before deploying, perform the following:

1. Modify the application.xml file with the modules of the enterprise Java application.

2. Archive all elements of the application into an EAR file.

Modify Application.XML

The application.xml file acts as the manifest file for the application and contains a list of the modules that are included within your enterprise application. You use each <module> element defined in the application.xml file to designate what comprises your enterprise application. Each module describes one of three things: EJB JAR, Web WAR, and any client files. Respectively, modify the <ejb>, the <web>, and the <java> elements in separate <module> elements.

• The <ejb> element specifies the EJB JAR filename.

• The <web> element specifies the Web WAR filename in the <web-uri> element and its context in the <context> element.

• The <java> element specifies the client JAR filename, if any.

As indicated in Figure 2-2, the application.xml file is located under a META-INF directory under the parent directory for the application. The JAR, WAR, and client JAR files should be contained within this directory. Because of this proximity, the application.xml file only refers to the JAR and WAR files by name and relative path--and not by full directory path. If these files were located in subdirectories under the parent directory, then these subdirectories must be specified in addition to the filename.

Figure 2-2 Archive Directory Format

Text description of the illustration primer2.gif

For example, the following example modifies the <ejb> and <web> module elements within application.xml for the Employee EJB application that also contains a servlet that interacts with the EJB.

<?xml version="1.0"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE 
Application 1.2//EN" "http://java.sun.com/j2ee/dtds/application_1_
2.dtd">
<application>
 <module>
  <ejb>Employee-ejb.jar</ejb>
 </module>
 <module>
  <web>
    <web-uri>Employee-web.war</web-uri>
    <context-root>/employee</context-root>
  </web>
 </module>
</application>

Create the EAR File

Create the EAR file that contains the JAR, WAR, and XML files for the application. Note that the application.xml file serves as the EAR manifest file.

To create the Employee.EAR file, execute the following in the employee directory that is shown in Figure 2-2:

% jar cvfM Employee.EAR . 

This archives the application.xml, the Employee-ejb.jar, and the Employee-web.war files into the Employee.ear file.

Deploy the Enterprise Application to OC4J

OC4J is aware of and deploys your application when it is configured within the server.xml file. There are three methods to provide application information within the server.xml file:

• modify configuration using OEM--this is the recommended procedure

• using admin.jar to modify the server.xml file

• updating the server.xml file manually

Oracle recommends the following:

• Use OEM if you are executing in a production environment. The DCM component of OEM must know about your application configuration.

• Use admin.jar or update the XML file manually only if you are executing in standalone mode. If you do update the XML files through either of these methods and your OC4J instance is part of the OEM managed environment, you must notify DCM of the XML changes through the following command:

  dcmctl updateConfig -ct oc4j
  
  

The sections below describe the OC4J methods. See Oracle9i Application Server Administrator's Guide and Oracle Enterprise Manager Administrator's Guide for information on OEM.

Using ADMIN.JAR To Modify SERVER.XML

OC4J contains a command-line deployment tool for deploying J2EE applications--the admin.jar command. The options for this command are listed in the Oracle9iAS Containers for J2EE User's Guide.

To deploy a J2EE application with the EAR file to a remote node, execute admin.jar, as follows:

java -jar admin.jar ormi://<host><:port>
	<username> <password> -deploy -file <path/filename>
	-deploymentName <appname> -targetpath <path/destination>

where

• The <host><:port> is the host and port of the OC4J server.

• The <username><password> is the administration username and password for the OC4J server.

• The -file <path/filename> indicates the local directory and filename for the EAR file.

• The -deploymentName <appname> variable is the name of the application.

• The -targetpath <path/destination> indicates what path on the server node to deploy the EAR file into. The default path is the applications/ directory. Oracle recommends that you provide a target path.

  Note: If you have a Web application within the EAR file, bind the Web application using the admin.jar -bindWebApp option.

Updating SERVER.XML Manually

In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> entry for each J2EE application. The path should be the full directory path and EAR filename. For our employee example, add the following to the server.xml file:

<application name="employee"
	path="/private/applications/Employee.EAR"
	auto-start="true" />

If you included a Web application portion, you must do the following to bind the Web application to the Web server. In *-web-site.xml, add a <web-app ...> entry for each Web application. The <application> variable should be the same value as provided in the server.xml file. The <name> should be the WAR file, without the WAR extension, for the Web application.

For Web application binding for the employee Web application, add the following:

<web-app application="employee" name="Employee-web" 

	root="/employee" /> 

Verifying Deployment

OC4J detects the addition of your application to server.xml. The OC4J server displays a message that your application has been deployed. This is the extent of installation in OC4J.

If the server does not notice your application in a timely manner, simply start (or restart) OC4J, and it will locate your application immediately.

If you modified server.xml using admin.jar or manual edit, and you are not executing OC4J in standalone mode, notify the DCM component within OEM of your XML file changes by executing the following:

dcmctl updateConfig -ct oc4j

For more information on DCM, see the DCM Appendix in the Oracle9i Application Server Administrator's Guide.