EJB 3.0 Support

In this release, OC4J supports a subset of the functionality specified in the EJB 3.0 public review draft (http://jcp.org/aboutJava/communityprocess/pr/jsr220/index.html).

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.

Oracle cannot guarantee backwards compatibility in all cases. For example, if the meaning or purpose of currently supported annotation changes when the EJB 3.0 specification is finalized, then you must make code changes to your EJB 3.0 OC4J application.

There are no OC4J-proprietary EJB 3.0 annotations. For all OC4J-specific configuration, you must still use the orion-ejb-jar.xml file. For more information, see Appendix A, "XML Reference for orion-ejb-jar.xml Elements".

In this release, OC4J supports the use of ejb-jar.xml except for object-relational entity mapping configuration(see "Implementing an EJB 3.0 Entity"): all such configuration must done using annotations only. For more information, see "What is the ejb-jar.xml File?".

In this release, OC4J does not support resource injection in the web container. For more information, see "How Do Annotations and Resource Injection Work?".

This section describes:

What JDK is Required?
How do You Define an EJB 3.0 Application?
How does OC4J Manage Persistence in an EJB 3.0 Application?

What JDK is Required?

If you are using EJB 3.0 and annotations, then you must use JDK 5.0.

If you are using EJB 3.0 without annotations, then you may use JDK 1.4. However, in this case, all EJB configuration must be done using the ejb-jar.xml and orion-ejb-jar.xml deployment descriptor. For an example of how to use EJB 3.0 with JDK 1.4, see the " Using EJB 3.0 EnityManager API in JDK 1.4" in http://www.oracle.com/technology/tech/java/ejb30.html.

How do You Define an EJB 3.0 Application?

For entities, an ejb-jar.xml file is not used. OC4J assumes that an application deployed without an ejb-jar.xml file is an EJB 3.0 application.

For session beans and message-driven beans, an ejb-jar.xml file is used. In this case, OC4J checks the ejb-jar element version attribute. If it is set to "3.0", OC4J assumes that the application is an EJB 3.0 application.

How does OC4J Manage Persistence in an EJB 3.0 Application?

In an EJB 3.0 application, OC4J delegates persistence operations to an entity manager. In this release, OC4J uses the TopLink persistence framework to implement its entity manager (see "TopLink Entity Manager").

TopLink Entity Manager

Oracle TopLink is an advanced, object-persistence and object-transformation framework that provides development tools and run-time capabilities that reduce development and maintenance efforts, and increase enterprise application functionality.

In this release, OC4J uses TopLink as the entity manager for EJB 3.0 entities.

For more information about the TopLink, see "What is TopLink?" in the Oracle TopLink Developer's Guide.

For EJB 3.0 projects, you configure persistence properties through annotations. OC4J translates these annotations into TopLink configuration.

You can customize this configuration using an ejb3-toplink-sessions.xml file. For more information, see:

Customizing the TopLink Entity Manager

At runtime, you can access TopLink API to take advantage of advanced TopLink features.

Typically, you use object-relational annotations (see "Configuring an EJB 3.0 Entity Container-Managed Relationship Field") to specify how you want OC4J to store a persistent field in the database and rely on the default TopLink configuration for each such annotation.

Alternatively, you can access the TopLink API in an EJB 3.0 entity application at run time by creating an ejb3-toplink-sessions.xml (see "What is the ejb3-toplink-sessions.xml File?") and toplink-ejb-jar.xml (see "What is the toplink-ejb-jar.xml File?") file and packaging them in the META-INF directory of the EJB-JAR that contains your EJB 3.0 entities:

To customize TopLink session-level options, you only need an ejb3-toplink-sessions.xml file.
To customize TopLink persistence-specific options, you need both an ejb3-toplink-sessions.xml and toplink-ejb-jar.xml file.

You can use the TopLink API to customize persistence by overriding annotations or by replacing annotations altogether. For example, you might use annotations for most of your object-relational mappings and an ejb3-toplink-sessions.xml and toplink-ejb-jar.xml file to specify object-relational mappings for a subset of complex relationships not suited to annotation.

If the only JDK 1.5 language extension that your entity classes use are annotations, you can use the TopLink Workbench to create and configure these files. Oracle recommends using the TopLink Workbench to create and configure these files.

To customize the TopLink persistence manager, do the following:

Create a relational TopLink Workbench project.

"Creating a Project" in the Oracle TopLink Developer's Guide
Configure the TopLink Workbench project classpath to include your JDK 1.5 compiled entity classes.

"Configuring Project Classpath" in the Oracle TopLink Developer's Guide
Configure the project deployment XML file name (as toplink-ejb-jar.xml) and save location.

"Configuring Project Deployment XML Options" in the Oracle TopLink Developer's Guide
Optionally, configure other TopLink project-level options.

"Configuring a Relational Project" in the Oracle TopLink Developer's Guide
Configure TopLink relational descriptors for the entity classes you want to customize.

"Creating a Relational Descriptor" in the Oracle TopLink Developer's Guide

"Configuring a Relational Descriptor" in the Oracle TopLink Developer's Guide
Configure TopLink relational mappings for the persistent fields you want to customize.

"Creating a Mapping" in the Oracle TopLink Developer's Guide

"Configuring a Relational Mapping" in the Oracle TopLink Developer's Guide
Export your TopLink Workbench project to the toplink-ejb-jar.xml XML file.

"Exporting Deployment XML Information" in the Oracle TopLink Developer's Guide
Create a TopLink sessions configuration file named ejb3-toplink-sessions.xml.

"Creating a Server Session" in the Oracle TopLink Developer's Guide
Set the ejb3-toplink-sessions.xml file primary project to your toplink-ejb-jar.xml file.

"Configuring a Primary Mapping Project" in the Oracle TopLink Developer's Guide
Optionally, configure any other TopLink session-level options.

"Configuring a Server Session" in the Oracle TopLink Developer's Guide
Save your TopLink Workbench sessions configuration file.
Package the ejb3-toplink-sessions.xml and toplink-ejb-jar.xml file in the META-INF directory of the EJB-JAR that contains your EJB 3.0 entities.

Note:

Alternativley, you can use JDeveloper to create the ejb3-toplink-sessions.xml and toplink-ejb-jar.xml file (see "Using EJB Development Tools".).