Skip Headers

Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# How do You Package and Deploy an EJB Application?

This section describes the following:

- General Packaging and Deployment Procedure

- Understanding EJB Deployment Descriptor Files

- Understanding Packaging

- Understanding Deployment

## 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

### What is the ejb-jar.xml File?

The `ejb-jar.xml` file is an EJB deployment descriptor file, and, when used, it describes the following:

- mandatory structural information about all included enterprise beans

- a descriptor for container managed relationships, if any

- an optional name of an ejb-client-jar file for the ejb-jar

- an optional application-assembly descriptor

When it is required, the `ejb-jar.xml` file describes EJB information applicable to any J2EE application server. This information may be augmented by application server-specific EJB deployment descriptor files (see "What is the orion-ejb-jar.xml File?" and "What is the toplink-ejb-jar.xml File?").

For more information, see "Configuring the ejb-jar.xml File".

#### EJB 3.0

If you are using EJB 3.0, this deployment descriptor file is optional: you can use annotations instead. In this release, OC4J supports the use of both EJB 3.0 annotations and `ejb-jar.xml` for all options except object-relational entity mapping configuration (see "Implementing an EJB 3.0 Entity"): all object-relational entity mapping configuration must done using annotations only. Configuration in the `ejb-jar.xml` file overrides annotations.

#### EJB 2.1

If you are using EJB 2.1, this deployment descriptor file is required.

#### XML Reference

The XML reference for this deployment descriptor file depends on the EJB version you are using.

For EJB 3.0, this deployment descriptor file conforms to the XML schema document located at `http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd`.

For EJB 2.1, this deployment descriptor file conforms to the XML schema document located at `http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd`.

Note: In this release (10.1.3.0.0), OC4J support for EJB 3.0 features is based on a pre-release version of EJB 3.0. Consequently, OC4J support for some EJB 3.0 features may differ from what is specified in the `ejb-jar_3_0.xsd` (for example, interceptors and lifecycle listeners). For a list of options that OC4J does not support, see the Oracle Application Server Release Notes. You may need to make code changes to your EJB 3.0 OC4J application after the EJB 3.0 specification is finalized and OC4J is updated to full EJB 3.0 compliance.

### What is the orion-ejb-jar.xml File?

The `orion-ejb-jar.xml` file is an EJB deployment descriptor file that contains all OC4J-proprietary options. This file extends the configuration that you specify in the `ejb-jar.xml` file (see "What is the ejb-jar.xml File?").

For more information, see "Configuring the orion-ejb-jar.xml File".

#### EJB 3.0

If you are using EJB 3.0, this file is mandatory for all OC4J-proprietary options because there are no OC4J-proprietary annotations. Alternatively, you could deploy without an `orion-ejb-jar.xml` file and configure OC4J-proprietary options with Application Server Control (see "How Do Specify Vendor-Specific Configuration in an EJB 3.0 Application?").

#### EJB 2.1

If you are using EJB 2.1, this file is mandatory for all OC4J-proprietary options.

#### XML Reference

This deployment descriptor file conforms to the XML schema document at `http://www.oracle.com/technology/oracleas/schema/orion-ejb-jar-10_0.xsd`.

### What is the toplink-ejb-jar.xml File?

The `toplink-ejb-jar.xml` file (also known as the TopLink `project.xml` file) is a TopLink persistence configuration descriptor file, and, when used, it describes TopLink project-level options (see "" in the Oracle TopLink Developer's Guide) such as TopLink descriptors and mappings.

For more information, see "Configuring the toplink-ejb-jar.xml File".

#### EJB 3.0

If you are using EJB 3.0, this file is only used to customize TopLink persistence manager configuration (see "Customizing the TopLink Entity Manager"). If you use this file to customize the TopLink persistence manager, you must also use an `ejb3-toplink-sessions.xml` file (see "What is the ejb3-toplink-sessions.xml File?").

#### EJB 2.1

If you are using EJB 2.1, this file is optional. If you omit this file from your application, you can configure OC4J to automatically construct it for your (see "Configuring Default Mappings"). Alternatively, you can use this file to configure TopLink persistence options yourself (see "Customizing the TopLink Persistence Manager").

#### XML Reference

The `toplink-ejb-jar.xml` file conforms to the XML schema documents located at `<``OC4J_HOME``>\toplink\config\xsds`. Oracle does not recommend manual configuration of this file. To create and configure this file, use the TopLink Workbench (see "Understanding the TopLink Workbench" in the Oracle TopLink Developer's Guide).

### What is the ejb3-toplink-sessions.xml File?

The `ejb3-toplink-sessions.xml` file is a TopLink persistence configuration descriptor file, and, when used, it describes TopLink session-level options (see "Configuring Server Sessions" in the Oracle TopLink Developer's Guide) such as data sources, login information, caching options, and logging. It is equivalent to the `sessions.xml` file that TopLink users are familiar with.

This file provides a reference to the primary project (see "What is the toplink-ejb-jar.xml File?"), if used.

For more information, see "Configuring the ejb3-toplink-sessions.xml File".

#### EJB 3.0

If you are using EJB 3.0, this file is only used to customize TopLink persistence manager configuration (see "Customizing the TopLink Entity Manager"). If you use this file to customize the TopLink persistence manager, you may also use a `toplink-ejb-jar.xml` file (see "What is the toplink-ejb-jar.xml File?").

#### EJB 2.1

If you are using EJB 2.1, this file is not used.

#### XML Reference

The `ejb3-toplink-sessions.xml` file conforms to the XML schema documents located at `<``OC4J_HOME``>\toplink\config\xsds`. Oracle does not recommend manual configuration of this file. To create and configure this file, use the TopLink Workbench (see "Understanding the TopLink Workbench" in the Oracle TopLink Developer's Guide).

## 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 ".

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

When you deploy an EJB 3.0 application, you must specify any vendor-specific configuration in one of the following ways:

- Package an `orion-ejb-jar.xml` with the desired vendor-specific configuration and deploy.

- After deployment, use the Application Server Control deployment profile to make the vendor-specific configuration.

For example, you can use annotations to define security roles but defining role-to-group mappings requires vendor-specific configuration. In this case, you can either define the role-to-group mappings in an `orion-ejb-jar.xml` file and package that in your application or, you can deploy your application without an `orion-ejb-jar.xml` and use Application Server Control to make this vendor-specific configuration after deployment.

### In What Order does OC4J Deploy EJB Modules?

OC4J deploys EJB modules in the order in which they appear in the `application.xml` deployment descriptor. In general, loading order is component-specific and base don natural ordering per component type.

For example, consider the `application.xml` file shown in Example 2-3.

Example 2-3 application.xml

    <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>

Based on this `application.xml` file, OC4J will load components in the following order:

1. `ejb1`

2. `ejb2`

3. `ejb3`

4. `clientweb.war`

5. `appclient.jar`