How do You Package and Deploy an EJB Application?

General Packaging and Deployment Procedure

In general, to package and deploy an EJB application:

1. 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 EJB module of the application. It describes the types of beans, their names, and attributes. The structure for this file is defined by the XML schema document (XSD) at http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd.

   Any EJB container services that you want to configure are designated in the deployment descriptor. For information, see "What OC4J Services Can You Use with an EJB?".

   You can also configure OC4J-specific options in the orion-ejb-jar.xml file (or using Application Server Control after deployment). For more information, see:

   • "Understanding EJB Deployment Descriptor Files"

   • "How Do Specify Vendor-Specific Configuration in an EJB 3.0 Application?"

   After creation, place the deployment descriptors for the EJB application in the META-INF directory that is located in the same directory as the EJB classes (see Figure 2-1).

   The following example shows the sections that are necessary for the Hello example, which implements both a remote and a local interface.

   Example 2-1 shows the deployment descriptor for a version of the Hello example that uses a stateless session bean. This example defines both the local and remote interfaces. You do not have to define both interface types; you may define only one of them.

   Example 2-1 ejb-jar.xml Deployment Descriptor for Hello Bean Application

   <?xml version="1.0" encoding="UTF-8" ?>
   <ejb-jar 
       xmlns="http://java.sun.com/xml/ns/j2ee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                           http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"
       version="2.1">
      <enterprise-beans>
         <session>
            <description>no description</description>
            <display-name>HelloBean</display-name>
            <ejb-name>HelloBean</ejb-name>
            <home>hello.HelloHome</home>
            <remote>hello.Hello</remote>
            <local-home>hello.HelloLocalHome</local-home>
            <local>hello.HelloLocal</local>
            <ejb-class>hello.HelloBean</ejb-class>
            <session-type>Stateless</session-type>
            <transaction-type>Container</transaction-type>
         </session>
      </enterprise-beans>
   
      <assembly-descriptor>
         <container-transaction>
            <method>
               <ejb-name>HelloBean</ejb-name>
               <method-name>*</method-name>
            </method>
            <trans-attribute>Supports</trans-attribute>
         </container-transaction>
         <security-role>
            <role-name>users</role-name>
         </security-role>
      </assembly-descriptor>
   </ejb-jar>
   
   

2. Archive the EJB Application

   After you have finalized your implementation and 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 Oracle Containers for J2EE Developer's Guide.

   
   

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

   % jar cvf helloworld-ejb.jar .
   
   

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

3. Prepare the EJB Application for Assembly

   To prepare the application for deployment, you do the following:

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

      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 as Table 2-3 shows.

      Table 2-3 Module Elements in the application.xml File

      Element	Contents
      <ejb>	EJB JAR filename
      <web>	Web WAR filename in the <web-uri> sub-element, and its context in the <context> sub-element
      <java>	Client JAR filename, if any

      
      

      As Figure 2-1 shows, 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 refers to the JAR and WAR files only by name and relative path—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.

      Example 2-2 modifies the <ejb>, <web>, and <java> module elements within application.xml for the Hello EJB application that also contains a Java client that interacts with the EJB.

      Example 2-2 application.xml Deployment Descriptor for Hello Bean

      <?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>
        <display-name>helloworld j2ee application</display-name>
        <description>
           A sample J2EE application that uses a Helloworld Session Bean
           on the server and calls from java/servlet/JSP clients.
        </description>
        <module>
          <ejb>helloworld-ejb.jar</ejb>
        </module>
        <module>
          <web>
            <web-uri>helloworld-web.war</web-uri>
            <context-root>/helloworld</context-root>
          </web>
        </module>
        <module>
          <java>helloworld-client.jar</java>
        </module>
      </application>
      
      

   2. Archive all elements of the application into an 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 helloworld.ear file, execute the following in the hello directory contained in Figure 2-1:

      % jar cvf helloworld.ear . 
      
      

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

Understanding EJB Deployment Descriptor Files

This section describes the various EJB deployment descriptor files that you use in EJB applications deployed to OC4J.

Table 2-4 lists the various EJB deployment descriptor files that you use in EJB applications deployed to OC4J. For each deployment descriptor file, it indicates the EJB types the deployment descriptor applies to and whether or not the deployment descriptor is optional, required, or not applicable to the EJB specification you are using.

Table 2-4 OC4J EJB Deployment Descriptor Files

Deployment Descriptor File	Session Bean	Entity	Entity Bean	Message- Driven Bean	EJB 3.0	EJB 2.1
What is the ejb-jar.xml File?					Optional	Required
What is the orion-ejb-jar.xml File?					Optional	Optional
What is the toplink-ejb-jar.xml File?					Optional	Required
What is the ejb3-toplink-sessions.xml File?					Optional	Not Applicable

Understanding Packaging

The J2EE architecture provides a variety of ways to package (or assemble) your application and its various J2EE components.

For more information, see "Packaging an EJB Application".

Understanding Deployment

After you package your J2EE application, to execute the application and make it available to end users, you deploy it to OC4J.

This section describes:

• How Do Specify Vendor-Specific Configuration in an EJB 3.0 Application?

• In What Order does OC4J Deploy EJB Modules?

For more information, see "Deploying an EJB Application to OC4J ".

<application>
  <display-name>master-application</display-name>
  <module>
    <ejb>ejb1.jar</ejb>
  </module>
  <module>
    <ejb>ejb2.jar</ejb>
  </module>
  <module>
    <java>appclient.jar</java>
  </module>
  <module>
    <web>
        <web-uri>clientweb.war</web-uri>
        <context-root>webapp</context-root>
    </web>
  </module>
  <module>
    <ejb>ejb3.jar</ejb>
  </module>