How do you Package and Deploy an EJB Application?

This section describes the following:

Understanding Packaging
Understanding Deployment
Understanding EJB Deployment Descriptor Files

Understanding Packaging

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

The most efficient way to package a Java EE application is to use a Java EE tool such as JDeveloper or Eclipse.

For more information, see the following:

"Using EJB Development Tools"
"Packaging an EJB Application"
Oracle Application Server Enterprise Deployment Guide

Understanding Deployment

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

The most efficient way to deploy a Java EE application to OC4J is to use Oracle Enterprise Manager 10g Application Server Control.

For more information, see the following:

"In What Order Does OC4J Deploy EJB Modules?"
"Understanding EJB Deployment Descriptor Files"
"Using Oracle Enterprise Manager 10g Application Server Control"
"Deploying an EJB Application to OC4J "
Oracle Application Server Enterprise Deployment Guide

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 based on natural ordering for each component type.

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

Example 2-1 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:

ejb1
ejb2
ejb3
clientweb.war
appclient.jar

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-3 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 to which the deployment descriptor applies and whether or not the deployment descriptor is optional, required, or not applicable to the EJB specification you are using.

Table 2-3 OC4J EJB Deployment Descriptor Files

Deployment Descriptor File	JPA Entity	EJB 3.0	EJB 2.1
"What is the ejb-jar.xml File?"		Optional	Required
"What is the orion-ejb-jar.xml File?"	^Foot 1	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 persistence.xml File?"		Optional	Not Applicable
"What is the orm.xml File?"		Optional	Not Applicable

^Footnote 1<entity-deployment> element disable-default-persistent-unit attribute only.

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 Java EE 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 of session and message-driven beans. The ejb-jar.xml file is not used for EJB 3.0 entities. Configuration in the ejb-jar.xml file overrides annotations (see "Overriding Annotations With Deployment Descriptor Entries").

For EJB 30. entities, you must either use annotations or TopLink JPA persistence provider deployment XML files (toplink-ejb-jar.xml and ejb3-toplink-sessions.xml).

For more information, see:

"What is the toplink-ejb-jar.xml File?"
"What is the ejb3-toplink-sessions.xml File?"

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.

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 the following:

EJB 3.0

If you are using EJB 3.0, this file is optional. You can deploy without an orion-ejb-jar.xml file and set OC4J-proprietary options using OC4J-proprietary annotations (such as @StatelessDeployment, @StatefulDeployment, and @MessageDrivenDeployment) or Application Server Control. Vendor extensions set in the orion-ejb-jar.xml file override extensions set using OC4J-proprietary annotations. Configuration in the orion-ejb-jar.xml file overrides annotations (see "Overriding Annotations With Deployment Descriptor Entries").

For more information, see the following:

EJB 2.1

If you are using EJB 2.1, orion-ejb-jar.xml file is mandatory for all OC4J-proprietary options.

For more information, see "Customizing the TopLink EJB 2.1 Persistence Manager".

XML Reference

This deployment descriptor file conforms to the XML schema document at http://www.oracle.com/technology/oracleas/schema/index.html.

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 JPA preview persistence configuration descriptor file, and, when used, it describes TopLink project-level options (see "Configuring a Relational Project" in the Oracle TopLink Developer's Guide) such as TopLink descriptors and mappings.

Note:

By default, OC4J uses the TopLink Essentials JPA persistence provider. In this case, you can configure TopLink descriptor-level options (including mappings) using TopLink JPA extensions ("Accessing TopLink API at Run Time With TopLink Essentials JPA Persistence").

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

EJB 3.0

If you are using EJB 3.0 with the default TopLink Essentials JPA persistence provider, this file is not used.

If you are using EJB 3.0, the toplink-ejb-jar.xml file is only used to customize TopLink JPA preview persistence provider configuration (see "Customizing the JPA Persistence Provider"). If you use this file to customize the TopLink persistence provider, 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, the toplink-ejb-jar.xml file is optional. If you omit this file from your application, you can configure OC4J to automatically construct it for you (see "Configuring Default Relationship Generation"). Alternatively, you can use this file to configure TopLink persistence options yourself (see "Customizing the TopLink EJB 2.1 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 JPA preview persistence configuration descriptor file, and, when used with the TopLink JPA preview persistence provider, 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.

Note:

By default, OC4J uses the TopLink Essentials JPA persistence provider. In this case, you can configure TopLink session-level options using TopLink JPA extensions ("Accessing TopLink API at Run Time With TopLink Essentials JPA Persistence").

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 with the default TopLink Essentials JPA persistence provider, this file is not used.

If you are using EJB 3.0, the ejb3-toplink-sessions.xml file is only used to customize TopLink JPA preview persistence provider configuration (see "Customizing the JPA Persistence Provider"). If you use this file to customize the TopLink JPA preview persistence provider, 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, the ejb3-toplink-sessions.xml 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).

What is the persistence.xml File?

The persistence.xml file is a persistence descriptor file that you use to define one or more persistence units in an EJB 3.0 application that uses entities.

In this release, you can define persistence.xml in an EJB JAR, WAR, or EAR.

A persistence unit defines an entity manager's configuration. You specify a persistence unit by name when you acquire an entity manager (see "Acquiring an EntityManager"). Alternatively, you can take advantage of the OC4J default persistence unit (see "Understanding OC4J Persistence Unit Defaults").

A persistence unit is a logical grouping of the following:

Entity manager: including, entity manager provider, the entity managers obtained from it, and entity manager configuration.
Data source (see "Specifying a Data Source in a Persistence Unit").
Vendor extensions (see "Configuring Vendor Extensions in a Persistence Unit").
Persistent managed classes: the classes you intend to manage using an entity manager, namely, entity classes, embeddable classes, and mapped superclasses (see "What Persistent Managed Classes Does This Persistence Unit Include?").

All persistent managed classes in a given persistence unit must be collocated in their mapping to a single database.
Mapping metadata: the information that describes how to map persistent managed classes to database tables. You can specify mapping metadata using annotations on persistent managed classes and orm.xml files (see "What is the orm.xml File?").

For more information, see the following:

Understanding OC4J Persistence Unit Defaults

To simplify persistence unit configuration, you can use the following OC4J features:

Smart Defaulting
Acquiring an Entity Manager by Default Persistence Unit Name

For more information, see the following:

Smart Defaulting

For EJB modules only, you can rely on OC4J to build a default persistence.xml file and configure it with appropriate default values to define a default persistence unit with a default name if:

You deploy an application without a persistence.xml and your application contains at least one class annotated with @Entity.
You deploy an application with an empty persistence.xml.

Acquiring an Entity Manager by Default Persistence Unit Name

If your application specifies one and only one persistence unit (either explicitly or by way of smart defaulting), you need not specify the persistence unit name when you acquire an entity manager. In this case, OC4J defaults the persistence unit name.

To disable this feature, set orion-ejb-jar.xml file attribute disable-default-persistent-unit to true.

If you disable this feature, you can still use the OC4J default persistence unit if you specify an empty persistence unit in a persistence.xml file, then, when you acquire an entity manager in that persistence unit's scope, you do not need to specify a persistence unit name. In this case, OC4J will use its own default persistence unit and will assume that all JPA entity classes in the persistence unit root belong to that persistence unit. You may specify one and only one such empty persistence unit in your application.

EJB 3.0

If you are using EJB 3.0 entities, the persistence.xml file is mandatory (unless you are using the OC4J default persistence unit).

EJB 2.1

If you are using EJB 2.1, the persistence.xml file is not used.

XML Reference

For EJB 3.0, this deployment descriptor file conforms to the XML schema document defined in the EJB 3.0 specification at http://java.sun.com/products/ejb/docs.html.

What is the orm.xml File?

The orm.xml file is the XML deployment descriptor you use to specify object-relational mapping configuration. You can use an orm.xml file as an alternative to annotations and to override annotations.

You can specify more than one orm.xml file and these files may be present anywhere on the class path.

For more information, see the following:

EJB 3.0

If you are using EJB 3.0 entities, the orm.xml file is optional.

EJB 2.1

If you are using EJB 2.1, the orm.xml file is not used.

XML Reference

For EJB 3.0, this deployment descriptor file conforms to the XML schema document defined in the EJB 3.0 specification at http://java.sun.com/products/ejb/docs.html.