EJB 2.1 Support

In this release, OC4J supports the functionality specified in the EJB 2.1 final release specification (http://java.sun.com/products/ejb/docs.html).

This section describes the following:

What JDK is Required?
How do you Define an EJB 2.1 Module?
How Does OC4J Manage Persistence in an EJB 2.1 Application?

What JDK is Required?

If you are using EJB 2.1, then you must use JDK 1.4 or higher.

How do you Define an EJB 2.1 Module?

By default, module version - ejb-jar.xml file <ejb-jar> element version attribute - is set to 2.x.

Typically, this value changes only if you explicitly set it to 3.0 or omit the ejb-jar.xml file.

The CMP version - ejb-jar.xml file <cmp-version> element - is independent of the EJB module version. For EJB 2.x CMP entity beans, you set <cmp-version> to 2.x.

Note that it is valid to have an EJB 3.0 module that uses both EJB 2.x CMP entity beans and EJB 3.0 entities.

For more information, see "Understanding EJB Persistence Services".

How Does OC4J Manage Persistence in an EJB 2.1 Application?

OC4J delegates persistence operations to a persistence manager. In this release, OC4J uses the TopLink persistence manager by default (see "TopLink EJB 2.1 Persistence Manager").

The Orion persistence manager is deprecated. Oracle recommends that you use OC4J and the TopLink persistence manager for new development. Using the migration tool (see "Migrating to the TopLink EJB 2.1 Persistence Manager"), you can easily migrate an existing OC4J application that uses EJB 2.0 entity beans with the Orion persistence manager to use EJB 2.0 entity beans with the TopLink persistence manager. For more information about the Orion persistence manager, see the Oracle Containers for J2EE Orion CMP Developer's Guide.

TopLink EJB 2.1 Persistence 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 persistence manager for EJB 2.1 entity beans with container-managed persistence. For more information about the TopLink persistence manager, see "What is TopLink?" in the Oracle TopLink Developer's Guide.

OC4J provides JAR files for the classes that make up the TopLink EJB 2.1 persistence manager implementation. For more information about persistence JAR files, see "EJB 2.1 Persistence JAR Files".

For EJB 2.1 projects, you use the TopLink Workbench (see "Understanding the TopLink Workbench" in the Oracle TopLink Developer's Guide) to configure persistence properties in the toplink-ejb-jar.xml file (see "What is the toplink-ejb-jar.xml File?"). When you migrate an Orion CMP application to TopLink persistence (see "Migrating to the TopLink EJB 2.1 Persistence Manager"), the TopLink migration tool automatically creates a TopLink Workbench project for you.

You can customize this configuration at run time using a TopLink customization class (see "Customizing the TopLink EJB 2.1 Persistence Manager").

EJB 2.1 Persistence JAR Files

OC4J uses the TopLink JAR files that Table 3-3 lists to provide the TopLink EJB 2.1 persistence manager implementation. These JAR files are located in the <ORACLE_HOME>/toplink/jlib directory.

Table 3-3 TopLink JAR Files

JAR File	Contents
`antlr.jar`	This JAR contains the
`toplink.jar`	This JAR contains all the classes that comprise the TopLink API, including classes with Oracle JDBC dependencies. If you want to use an Oracle JDBC driver version different than the default version installed with OC4J, see "Associating TopLink With an Oracle JDBC Driver".
`toplink-agent.jar`	This JAR contains the classes that TopLink uses to perform byte-code weaving on EJB 2.1 entity bean classes to enable transparent one-to-one and many-to-one indirection without requiring the use of a `ValueHolder`. You invoke `toplink-agent.jar` by adding `-javaagent:toplink-agent.jar` to your application's JVM command line – do not include this jar on the classpath of a TopLink application. This JAR is optional. It should never be placed on the classpath and should only be used as part of `-javaagent`.
`toplink-oc4j.jar`	This JAR contains the classes that TopLink uses to integrate with Oracle Containers for J2EE. This JAR file is only used in OC4J; the container is preconfigured to use `toplink-oc4j.jar`. In a non-OC4J application, use `toplink.jar`.

Customizing the TopLink EJB 2.1 Persistence Manager

At run time, you can access TopLink persistence manager API to take advantage of advanced TopLink features.

To access the TopLink persistence manager API in an EJB 2.1 CMP application, you can include a TopLink customization class in your deployment JAR.

This optional Java class implements oracle.toplink.ejb.cmp.DeploymentCustomization to allow deployment customization of TopLink mapping and run-time configuration. At deployment time, the TopLink runtime creates a new instance of this class and invokes its methods beforeLoginCustomization (before the TopLink runtime logs in to the session) and afterLoginCustomization (after the TopLink runtime logs in to the session), passing in the TopLink session as a parameter.

Use your implementation of the beforeLoginCustomization method to configure TopLink session attributes including cache coordination, parameterized SQL, native SQL, batch writing/batch size, byte-array/string binding, login, event listeners, table qualifier, and sequencing.

For EJB 2.1, you can use a TopLink customization class to access TopLink persistence manager API not accessible from the TopLink Workbench GUI.

For more information, see the following:

"Configuring pm-properties" in the Oracle TopLink Developer's Guide
Oracle TopLink API Reference

Migrating to the TopLink EJB 2.1 Persistence Manager

Using the TopLink migration tool, you can easily migrate an existing OC4J application that uses EJB 2.0 entity beans with the Orion persistence manager to use EJB 2.0 entity beans with the TopLink persistence manager.

For more information on using the TopLink migration tool, see "Migrating OC4J Orion Persistence to OC4J TopLink Persistence" in the Oracle TopLink Developer's Guide.