| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
 Previous |
 Next |
| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
Previous |
Next |
This chapter describes:
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 backward 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:
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.
For entities, OC4J assumes that the application is an EJB 3.0 application if an EJB JAR is deployed without an ejb-jar.xml file. For more information, see "How Does OC4J Determine What Type of Persistence to Use?"
For session beans and message-driven beans, OC4J assumes that the application is an EJB 3.0 application if the ejb-jar.xml file <ejb-jar> element version attribute is set to "3.0"
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").
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:
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 theejb3-toplink-sessions.xml and toplink-ejb-jar.xml file (see "Using EJB Development Tools".). |
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:
For CMP entity beans, OC4J assumes that the application is an EJB 2.1 application if the ejb-jar.xml file <cmp-version> element is set to 2.x. For more information, see "How Does OC4J Determine What Type of Persistence to Use?".
For session beans and message-driven beans, OC4J assumes that the application is an EJB 2.1 application if the ejb-jar.xml file <ejb-jar> element version attribute is set to "2.1".
OC4J delegates persistence operations to a persistence manager. In this release, OC4J uses the TopLink persistence manager by default (see "TopLink 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 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.
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 CMP entity beans.
For more information about the TopLink persistence manager, see "What is TopLink?" in the Oracle TopLink Developer's Guide.
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 Persistence Manager"), the TopLink migration tool automatically creates a TopLink Workbench project for you.
You can customize this configuration at runtime using a TopLink customization class (see "Customizing the TopLink Persistence Manager").
At runtime, 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 run time creates a new instance of this class and invokes its methods beforeLoginCustomization (before the TopLink run time logs into the session) and afterLoginCustomization (after the TopLink runtime logs into 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:
"Configuring pm-properties" in the Oracle TopLink Developer's Guide
Oracle TopLink API Reference
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.
This section lists the following configuration changes introduced in this release:
For a complete list of new and deprecated OC4J features, see the 10g Release 3 (10.1.3) Oracle Application Server Release Notes.
In this release, note the new package names for the following initial context factories:
oracle.j2ee.rmi.RMIInitialContextFactory
oracle.j2ee.naming.ApplicationClientInitialContextFactory
For more information, see "Configuring the Initial Context Factory".
The following orion-ejb-jar.xml file attributes are unsupported:
max-instances-per-pk
min-instances-per-pk
disable-wrapper-cache
instance-cache-timeout
locking-mode="old_pessimistic"
|
Note: Do not use these attributes in this release. Doing so will lead to deployment failure. |
For more information, see Appendix A, "XML Reference for orion-ejb-jar.xml Elements".
