| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g (10.1.3.5.0) Part Number E13981-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g (10.1.3.5.0) Part Number E13981-01 |
|
|
View PDF |
In this release, OC4J supports all but a small subset of the functionality specified in the final EJB 3.0 specification (http://jcp.org/aboutJava/communityprocess/pr/jsr220/index.html).
You may need to make minor code changes to your EJB 3.0 OC4J application after OC4J is updated to full EJB 3.0 compliance. For more information, see "Migrating a 10.1.3.0 TopLink JPA Preview Application to 10.1.3.1 TopLink Essentials JPA".
In this release, OC4J supports the use of annotations, standard deployment XML (ejb-jar.xml or orion-ejb-jar.xml), or both for all EJB 3.0 features except for the object-relational entity mapping types (namely basic, binary large object (LOB), serialized, one-to-one, many-to-one, one-to-many, many-to-many, and aggregate mappings). For these, you must either use annotations or TopLink JPA persistence provider customization.
OC4J supports the proprietary EJB 3.0 annotations that the Oracle Application Server Annotations API Reference describes.
For more information, see:
In this release, OC4J supports resource injection in the Web tier. For more information, see "Annotations in the Web Tier".
This section describes the following:
By default, if you are using EJB 3.0, then you must use JDK 1.5. By default, OC4J does not support the use of EJB 3.0 and JDK 1.4.
OC4J supports the use of EJB 3.0 (excluding annotations and interceptors) with JDK 1.4 only with the TopLink JPA preview persistence provider. For more information, see the discussion of system property default.persistence.provider in "JPA Persistence JAR Files".
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 "Understanding EJB Persistence Services"
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 a JPA persistence provider: in this release, OC4J uses TopLink Essentials, the JPA persistence provider for the EJB 3.0 Reference Implementation (see "TopLink Essentials JPA Persistence Provider").
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 manages EJB 3.0 entities using TopLink Essentials, the JPA persistence provider for the EJB 3.0 Reference Implementation. For more information, see "What is TopLink?" in the Oracle TopLink Developer's Guide.
OC4J provides JAR files for both the classes that the EJB 3.0 persistence specification mandates and the classes that make up the TopLink Essentials JPA persistence provider implementation. For more information about persistence JAR files, see "JPA Persistence JAR Files".
For EJB 3.0 projects, you configure persistence properties through annotations or persistence.xml file. OC4J translates this metadata into TopLink configuration. For more information on customizing the TopLink Essentials EJB 3.0 JPA persistence provider, see "Customizing the JPA Persistence Provider".
OC4J uses the JAR files that Table 3-1 lists to provide the TopLink Essentials JPA persistence provider implementation. These JAR files are located in the <ORACLE_HOME>/toplink/jlib directory.
The system property default.persistence.provider determines which JPA persistence provider implementation OC4J uses. The following are valid values:
essentials (default): OC4J uses the <ORACLE_HOME>/j2ee/home/lib/persistence.jar to provide EJB 3.0 JPA classes that the EJB 3.0 persistence specification mandates and <ORACLE_HOME>/toplink/jlib/toplink-essentials.jar and toplink-essentials-agent.jar for the persistence provider implementation, providing full support for the final EJB 3.0 persistence specification.
toplink: OC4J uses the <ORACLE_HOME>/j2ee/home/lib/preview-persistence.jar to provide EJB 3.0 JPA classes that the public review EJB 3.0 persistence specification mandated and <ORACLE_HOME>/toplink/jlib/toplink.jar as the persistence provider implementation, providing a JPA preview based on a subset of the functionality specified in the EJB 3.0 public review draft. You can use this option to run an application written to the preview API. Oracle does not recommend that you use this option.
Table 3-1 TopLink JAR Files
| JAR File | Contents |
|---|---|
|
|
This JAR file contains the Antlr (ANother Tool for Language Recognition) tool. |
|
|
This JAR file 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". |
|
|
This JAR file contains the open source JPA edition of TopLink, the JPA persistence provider for the EJB 3.0 Reference Implementation. |
|
|
This JAR file contains the classes that TopLink uses to perform byte-code weaving on JPA entities to automatically enable features such as This JAR file provides part of TopLink Essentials, the JPA persistence provider for the EJB 3.0 Reference Implementation. It is used with This JAR is optional. It should never be placed on the classpath and should only be used as part of |
|
|
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 |
Typically, you use object-relational annotations (see "Configuring a Container-Managed Relationship Field for a JPA Entity") to specify how you want OC4J to store a persistent field in the database and rely on the default TopLink EJB 3.0 JPA persistence provider configuration for each such annotation. However, you may wish to override this default behavior to suit your application requirements. As well, although the TopLink EJB 3.0 JPA persistence provider is JPA compliant, it provides additional extensions beyond what is defined in the JPA specification.
You may customize the OC4J JPA persistence provider in any of the following ways:
Set vendor-specific query hints in a named or dynamic query (see "Configuring TopLink Query Hints in a JPA Query").
Set vendor-specific properties in the persistence.xml file using a <properties> element or in the Map of properties passed into the javax.persistence.Persistence method createEntityManagerFactory (see "Configuring Vendor Extensions in a Persistence Unit").
If you are using the TopLink Essentials persistence provider (default), you can access TopLink API in a JPA entity application at run time by using TopLink JPA extensions ("Accessing TopLink API at Run Time With TopLink Essentials JPA Persistence").
If you are using the TopLink JPA preview persistence provider, you can access the TopLink API in a JPA entity application at run time by creating an ejb3-toplink-sessions.xml and toplink-ejb-jar.xml file and packaging them in the META-INF directory of the EJB-JAR that contains your EJB 3.0 entities (see "Accessing TopLink API at Run Time With TopLink JPA Preview Persistence").
Configure the TopLink EJB 3.0 JPA persistence provider to use an Oracle JDBC driver version different than the default version installed with OC4J (see "Associating TopLink With an Oracle JDBC Driver").
If you are using the TopLink Essentials JPA persistence provider (default), you access TopLink API in a JPA entity application at run time by using TopLink JPA extensions toplink.session.customizer and toplink.descriptor.customizer.<ENTITY> (see Table 26-5).
If you are using the TopLink JPA preview persistence provider, you access the TopLink API in a JPA entity application at run time by creating an ejb3-toplink-sessions.xml file (see "What is the ejb3-toplink-sessions.xml File?") and toplink-ejb-jar.xml (see "What is the toplink-ejb-jar.xml File?") file.
Note:
By default, OC4J uses the TopLink Essentials JPA persistence provider. In this case, you access TopLink API in a JPA entity application at run time by using TopLink JPA extensions (see "Accessing TopLink API at Run Time With TopLink Essentials JPA Persistence").You package these files 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 JPA preview persistence provider, do the following:
Create a relational TopLink Workbench project (see "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 (see "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 (see "Configuring Project Deployment XML Options" in the Oracle TopLink Developer's Guide).
Optionally, configure other TopLink project-level options (see "Configuring a Relational Project" in the Oracle TopLink Developer's Guide).
Configure TopLink relational descriptors for the entity classes you want to customize (see "Creating a Relational Descriptor" in the Oracle TopLink Developer's Guide and "Configuring a Relational Descriptor" in the Oracle TopLink Developer's Guide).
Configure TopLink relational mappings for the persistent fields you want to customize (see "Creating a Mapping" in the Oracle TopLink Developer's Guide and "Configuring a Relational Mapping" in the Oracle TopLink Developer's Guide).
Export your TopLink Workbench project to the toplink-ejb-jar.xml XML file (see "Exporting Deployment XML Information" in the Oracle TopLink Developer's Guide).
Create a TopLink sessions configuration file named ejb3-toplink-sessions.xml (see "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 (see "Configuring a Primary Mapping Project" in the Oracle TopLink Developer's Guide).
Optionally, configure any other TopLink session-level options (see "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:
Alternatively, you can use JDeveloper to create the
ejb3-toplink-sessions.xml and toplink-ejb-jar.xml file (see "Using EJB Development Tools".).In 10.1.3.0 release, OC4J uses the TopLink JPA preview persistence provider based on a subset of the functionality specified in the EJB 3.0 public review draft.
In 10.1.3.1 release, OC4J uses the TopLink Essentials JPA persistence provider, the JPA persistence provider for the EJB 3.0 Reference Implementation, to provide full JPA support according to the final EJB 3.0 specification.
You must make code changes to your JPA preview-based application before using it with TopLink Essentials and the final EJB 3.0 API in OC4J 10.1.3.1.
In general, you should do the following:
Undeploy your preview-based application.
Upgrade OC4J from 10.1.3.0 to 10.1.3.1.
Make the necessary post-upgrade configuration file changes (see "Changes in OC4J Configuration Files").
Migrate your code to use the new EJB 3.0 API.
The following sections describe the important differences between the TopLink JPA preview and full TopLink JPA to help you identify where changes must be made:
Redeploy your updated application.
After applying the 10.1.3.1.0 patch set to a 10.1.3.0.0 OC4J, you must manually edit OC4J configuration files as follows:
Edit the <ORACLE_HOME>/j2ee/home/config/server.xml file and add the following:
<shared-library name="oracle.persistence" version="1.0" library-compatible="true">
<code-source path="../../../toplink/jlib/toplink-essentials.jar"/>
</shared-library>
Edit the <ORACLE_HOME>/j2ee/home/config/system-application.xml file and add the following to the <imported-shared-libraries> element:
<import-shared-library name="oracle.persistence"/>
Table 3-2 lists the additions, deletions, and changes made to the javax.persistence package between 10.1.3.0 and 10.1.3.1. If your application uses any of these classes, consult the latest EBJ 3.0 specification and JPA Javadoc for details.
Table 3-2 Changes to javax.persistence
| 10.1.3.0 | 10.1.3.1 | Description |
|---|---|---|
|
|
deleted |
In 10.1.3.1 release, EJB 3.0 entities do not require local or remote interfaces. Because all entity access is by way of an |
|
|
deleted |
In 10.1.3.1 release, the EJB 3.0 persistence specification requires the use of a single access type in an entity hierarchy. The placement of the mapping annotations determines the access type in effect. |
|
N/A |
|
Added in 10.1.3.1 release as part of the changes made to annotations for inheritance. For more information, see |
|
N/A |
|
Added in 10.1.3.1 release as part of the changes made to annotations for inheritance. For more information, see |
|
|
|
In 10.1.3.1 release, attribute For more information, see |
|
N/A |
|
Added in 10.1.3.1 release as part of the changes made to annotations for inheritance. For more information, see |
|
|
deleted |
Added in 10.1.3.1 release as part of the changes made to annotations for inheritance. For more information, see |
|
|
|
In 10.1.3.1 release, attribute |
|
N/A |
|
Added in 10.1.3.1 release. |
|
|
deleted |
In 10.1.3.1 release, use For more information, see |
|
N/A |
|
Added in 10.1.3.1 release. For more information, see |
|
|
|
In 10.1.3.1 release, New methods added in 10.1.3.1 include the following:
In 10.1.3.1 release, methods of this class throw additional exceptions such as |
|
|
|
In 10.1.3.1 release, this exception extends |
|
|
|
New methods added in 10.1.3.1 release include the following:
|
|
|
deleted |
In 10.1.3.1 release, the EJB 3.0 specification removes the concept of BMP. To develop and deploy a Java EE 5 BMP application, you must use the EJB 2.1 API. |
|
N/A |
|
Added in 10.1.3.1 release to support direct mappings of enumerated types. For more information, see |
|
N/A |
|
Added in 10.1.3.1 release to support direct mappings of enumerated types. For more information, see |
|
N/A |
|
Added in 10.1.3.1 release to support managing life cycle callback default listeners. For more information, see |
|
N/A |
|
Added in 10.1.3.1 release to support managing life cycle callback superclass listeners. For more information, see |
|
|
deleted |
In 10.1.3.1 release, to set the flush mode, use the |
|
N/A |
|
Added in 10.1.3.1 release to support automatic primary key (identity) generation. For more information, see |
|
N/A |
|
Added in 10.1.3.1 release to support automatic primary key (identity) generation. For more information, see |
|
|
deleted |
In 10.1.3.1 release, use |
|
|
|
In 10.1.3.1 release, the following attributes are omitted:
For more information, see |
|
|
|
In 10.1.3.1 release, attribute For more information, see |
|
|
|
In 10.1.3.1 release, attribute The following attributes are added:
For more information, see |
|
|
deleted |
In 10.1.3.1 release, use direct mapping annotation For more information, see |
|
N/A |
|
Added in 10.1.3.1 release. |
|
N/A |
|
Added in 10.1.3.1 release as part of the changes made to annotations for inheritance. For more information, see |
|
|
|
In 10.1.3.1 release, attribute For more information, see |
|
|
|
In 10.1.3.1 release, attribute For more information, see |
|
|
|
In 10.1.3.1 release, this exception extends |
|
N/A |
|
Added in 10.1.3.1 release. |
|
|
|
In 10.1.3.1 release, attribute For more information, see |
|
N/A |
|
For more information, see |
|
N/A |
|
For more information, see |
|
N/A |
|
Added in 10.1.3.1 release. |
|
|
|
In 10.1.3.1 release, attribute For more information, see |
|
|
|
In 10.1.3.1 release, the default for attribute For more information, see |
|
N/A |
|
For more information, see |
|
|
|
In 10.1.3.1 release, attribute For more information, see |
|
|
|
In 10.1.3.1 release, the following attributes were added:
For more information, see |
|
N/A |
|
For more information, see |
|
|
|
In 10.1.3.1 release, enum value For more information, see |
|
|
|
In 10.1.3.1 release, this exception extends |
In 10.1.3.1 release, the following new classes were added:
DerbyPlatform
JavaDBPlatform
PostgreSQLPlatform
If you are using TopLink JPA with OC4J, be aware of the fact that interceptors changed substantially between the TopLink JPA preview and the final EJB 3.0 specification.
In the final EJB 3.0 specification, interceptors and life cycle event listeners are merged and both use javax.interceptors.Interceptors. This will affect any code that uses interceptors or life cycle event listeners, in particular session beans and message-driven beans.
For more information, see the following:
In 10.1.3.0 release, you use the java.persistence.setup.config property to identify a class with the list of entities that an entity manager manages.
In 10.1.3.1 release, this property is obsolete. Instead, you must define managed entity classes in a persistence unit as specified in the EJB 3.0 specification.
In 10.1.3.0 release, you inject an entity manager using the @Resource annotation.
In 10.1.3.1 release, you inject an entity manager using the @PersistenceContext annotation:
@PersistenceContext protected EntityManager entityManager;
In 10.1.3.1 release, OC4J supports the use of @Resource to inject an entity manager for backward compatibility. However, Oracle recommends that you use the @PersistenceContext annotation instead to be compliant with the EJB 3.0 specification.
For more information, see the following:
In 10.1.3.0 release, OC4J uses the persistence-preview.jar and toplink.jar file to provide the JPA preview implementation.
In 10.1.3.1 release, OC4J uses the persistence.jar and the toplink-essentials.jar and toplink-essentials-agent.jar files to provide the full JPA implementation.
In your IDE, ensure that any library definitions you may have associated with your projects include only the 10.1.3.1 JPA libraries and exclude the old 10.1.3.0 libraries.
For more information about TopLink JAR files, see "JPA Persistence JAR Files".
|
 Copyright © 2002, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|