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:

1. ejb1
2. ejb2
3. ejb3
4. clientweb.war
5. 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

EJB
JPA 2.1 Message-
Deployment Sessio Entit Entity Driven EJB
Descriptor File n Bean y Bean Bean 3.0 EJB 2.1
"What is the Option Required
ejb-jar.xml File?" al

"What is the Foot 1

Option Optional
orion-ejb-jar.xml al
File?"

"What is the Option Required

toplink-ejb- al
jar.xml File?"

"What is the Option Not

ejb3-toplink- al Applicabl
sessions.xml e
File?"

"What is the Option Not

persistence.xml al Applicabl
File?" e

"What is the Option Not

orm.xml File?" al Applicabl
e
 <entity-deployment> element disable-default-
Footnote 1

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:

• "Configuring the orion-ejb-jar.xml File"

• "XML Reference for orion-ejb-jar.xml Elements"

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:

• "Configuring OC4J-Proprietary Deployment Options on an EJB 3.0

Session Bean"
• "Configuring OC4J-Proprietary Deployment Options on an EJB 3.0
MDB"
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>toplinkconfigxsds. 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>toplinkconfigxsds. 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:

• "Configuring the persistence.xml File"

• "Packaging a JPA Entity Application"
• EJB 3.0 specification

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:

• "Configuring the persistence.xml File for the OC4J Default

Persistence Unit"
• "Acquiring an EntityManager"

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:

• "What is the persistence.xml File?"

• "Packaging a JPA Entity Application"

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.