This chapter describes Oracle TopLink, the default persistence provider in Oracle WebLogic Server 12.1.3, and introduces how to use it. This chapter also tells how to set the default persistence provider in WebLogic Server, how to modify existing Kodo applications for use in the current release, and how to upgrade to a newer version of OpenJPA.
6 Patching Individual Applications, Domains, or Servers. Smart Update enables you to point a domain or server at a set of patches that are not necessarily intended for the entire installation by using a custom patch.
This chapter includes the following sections:
Overview of Oracle TopLink
Oracle TopLink is the default persistence provider in WebLogic Server 12c and later. It is a comprehensive standards-based object-persistence and object-transformation framework that provides APIs, schemas, and run-time services for the persistence layer of an application.
The core component of TopLink is the EclipseLink project's produced libraries and utilities. EclipseLink is the open source implementation of the development framework and the runtime provided in TopLink. EclipseLink implements the following specifications, plus value-added extensions:
- Java Persistence 2.0 (JPA 2.0).JPA 2.0 is part of Java Platform, Enterprise Edition 6 (Java EE 6). It includes improvements and enhancements to domain modeling, object/relational mapping,
EntityManager
andQuery
interfaces, and the Java Persistence Query Language (JPQL). It includes an API for criteria queries, a metamodel API, and support for validation.For the JPA 2.0 Specification, see 'JSR-000317 Java Persistence 2.0' athttp://jcp.org/aboutJava/communityprocess/final/jsr317/index.html
. - Java Architecture for XML Binding (JAXB) 2.2. (The EclipseLink JAXB implementation, plus EclipseLink extensions, is called MOXy.)For the JAXB 2.0 specification, see 'JSR-000222 Java Architecture for XML Binding (JAXB) 2.0 ' at
http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html
. - EclipseLink also includes Database Web Service (DBWS), which provides access to relational database artifacts by using a Java API for XML Web Services (JAX-WS) 2 Web service.
EclipseLink also provides support for Oracle Spatial and Oracle XDB mapping.
For more information about EclipseLink, including other supported services, see the EclipseLink project home at
http://wiki.eclipse.org/EclipseLink
and the EclipseLink Documentation Center at http://wiki.eclipse.org/EclipseLink/UserGuide
.In addition to all of EclipseLink, Oracle TopLink includes:
- TopLink Grid, an integration between EclipseLink JPA with Oracle Coherence that allows EclipseLink to use Oracle Coherence as a level 2 (L2) cache and persistence layer for entities. For more information, see Developing Applications with Oracle Coherence and Oracle Fusion Middleware Integration Guide for Oracle TopLink with Coherence Grid.Note:You must have a license for Oracle Coherence to be able to use TopLink Grid.
- Logging integration with WebLogic Server.
- MBean support in WebLogic Server.
For information about developing, deploying, and configuring Oracle TopLink applications, see the following:
- EclipseLink Documentation Center at
http://wiki.eclipse.org/EclipseLink/UserGuide
- EclipseLink examples at
http://wiki.eclipse.org/EclipseLink/Examples
.
Specifying a Persistence Provider
You can specify what persistence provider to use for a persistence unit in the application code or by accepting the default persistence provider set for the WebLogic Server domain, as described in the following sections:
Setting the Default Provider for the Domain
Unless you specify otherwise, TopLink is used as the default persistence provider for a WebLogic Server domain. The default provider is used for any entities in an application that are not configured to use a different persistence provider. The default provider is used for both injected and application-managed entity managers and factories.
You can set the default provider in the WebLogic Server Administration Console or by directly setting
JPAMBean.DefaultJPAProvider
. In the WebLogic Server Administration Console, the options are Oracle TopLink or Oracle Kodo.Note:
Oracle Kodo JPA/JDO is deprecated in this release. Customers are encouraged to use Oracle TopLink, which supports JPA 2.0. Kodo supports only JPA 1.0.For instructions on setting the default through the WebLogic Server Administration Console, see 'Configure the Default JPA Persistence Provider' in Oracle WebLogic Server Administration Console Online Help.
If you change the default provider, you must do the following for any deployed applications that do not specify a JPA provider:
- Restart applications that use application-managed entity manager factories.
- Redeploy applications that use injected entity manager factories or entity managers.
Specifying the Persistence Provider in an Application
A persistence provider specified in an application takes precedence over the default provider set for the WebLogic Server domain.
You can set the provider to use in the following ways:
- Specify the provider in the
<provider>
element for a persistence unit in thepersistence.xml
file, for example: - Specify the provider in the
javax.persistence.provider
property passed to theMap
parameter of thejavax.persistence.Persistence.createEntityManagerFactory(String, Map)
method.
Using Oracle TopLink in Oracle WebLogic Server
For detailed information about using Oracle TopLink in WebLogic server, see 'Using TopLink with WebLogic Server' in Solutions Guide for Oracle TopLink.
Using JPA 2.1 with Oracle TopLink in WebLogic Server
When you use Oracle TopLink as the persistence provider in this release of WebLogic Server, you can install a patch that provides support for the Java Persistence Architecture (JPA) 2.1. If you do not apply this patch, JPA 2.0 is supported by default.
Note:
Support for JPA 2.1 in WebLogic Server is provided as a patch because JPA 2.1 is part of the Java Platform, Enterprise Edition (Java EE) 7. Therefore, enabling JPA 2.1 support in the current release results in WebLogic Server not meeting all Java EE 6 compatibility requirements. To maintain Java EE 6 compatibility, the files required for JPA 2.1 support are not enabled by default, although they are included in a standard WebLogic Server installation.JPA 2.1 includes new support or enhancements for features including Criteria Bulk Update/Delete, stored procedures, JPQL Generic function, injectable entity listeners,
TREAT
, converters, DDL generation, and entity graphs. For the complete JPA 2.1 specification, see 'JSR-000338 Java Persistence 2.1 (Final Release)' at http://jcp.org/aboutJava/communityprocess/final/jsr338/index.html
.To use JPA 2.1 in this release of WebLogic Server:
- Use Oracle TopLink as the persistence provider, as described in 'Using TopLink with WebLogic Server' in Solutions Guide for Oracle TopLink.
- Apply the patch, using either of the following methods:
Applying the Patch Using OPatch
OPatch is a Java-based utility that runs on all supported operating systems and is automatically included with WebLogic Server when you use the generic installer. It is used to apply patches to Oracle software. For information on using OPatch, see Patching with OPatch.
To download the patch that enables JPA 2.1 support, log in to My Oracle Support at
http://support.oracle.com/
. Select the Patches and Updates page, and enter the patch number, 17754607, in the search field.Applying the Patch Manually
Note:
Oracle recommends using OPatch to apply patches to WebLogic Server. However, if you created your WebLogic Server installation with the developer-only installer, which does not include OPatch, you can install the patch manually as described in this section.![How How](/uploads/1/2/6/3/126357355/923363006.png)
The files required for supporting JPA 2.1 are included with a default WebLogic Server installation, but they are not enabled by default. The files are:
- The
javax.persistence_2.1.jar
file that contains the JPA 2.1 libraries. This file is installed in theORACLE_HOME
oracle_commonmodules
directory. - The
com.oracle.weblogic.jpa21support_1.0.0.0_2-1.jar
file that contains the files for enabling JPA 2.1 support in WebLogic Server. This file is installed in theWL_HOME
modules
directory.
You can install the patch manually by putting the files at the start of the WebLogic classpath. For example, you can use either of the following methods:
- Define a
PRE_CLASSPATH
environment variable before starting WebLogic Server.For example, in a Windows console window, run the following script before runningstartWebLogic.cmd
:A similar script can be written for Linux, UNIX, or Macintosh.Note:Before running this script, run thesetDomainEnv
script, located in theDOMAIN_HOMEbin
directory, to make sure thatMW_HOME
is properly set. - Modify the
commEnv.cmd
orcommEnv.sh
script in theWL_HOME
commonbin
directory and add thePRE_CLASSPATH
at the beginning of the script, setting it to the paths of the JPA 2.1 JAR file and the JPA 2.1 patch.
Using Oracle Kodo in Oracle WebLogic Server
It is advantageous to use the default Oracle TopLink for your applications, due to its implementation of JPA 2.0, its enhanced set of features, its integration in WebLogic Server, and its integration with TopLink Grid. However, you may want to continue to use Kodo for existing applications that were written for use with Kodo. Although deprecated, Kodo is still included with WebLogic Server: you do not have to install it. You can set it as the default provider, as described in Specifying a Persistence Provider, or configure an application to use it.
Note:
Switching an application from one JPA provider to another usually involves more than just flipping a switch. Most obviously, if the application uses proprietary features of the original JPA implementation, that usage will have to change when moving to a different implementation.In addition, differences in the implementations of a standard specification (that is, JPA) can affect the behavior of an application. Although Kodo and TopLink implement their JPA specifications, as do other conforming JPA implementations, each implementation makes its own decisions about unspecified details that can affect the behavior of the application using JPA. When making the switch from one JPA implementation to another, the application should be thoroughly tested with the expectation that some behavioral differences will have to be corrected.
If you use Kodo, note the information described in the following sections:
Using JPA 1.0 APIs
You cannot use any JPA 2 APIs with Kodo. Because Kodo supports only JPA 1, trying to use any JPA 2 APIs will generate an error.
Using persistence-configuration.xml
The Kodo
persistence-configuration.xml
descriptor is valid only when Kodo is the persistence provider. If you include a persistence-configuration.xml
in an application that uses injection and you do not specify Kodo as the persistence provider, the persistence-configuration.xml
descriptor is ignored and a warning is issued.Updating Applications to Overcome Conflicts with JPA 2.0
Kodo is based on open-source OpenJPA 1.x, the JPA 1.0 framework and provider from the Apache Foundation. Although JPA 1.0 is upwardly compatible with JPA 2.0, JPA 2.0 introduced some methods to existing JPA interfaces that conflict with existing signatures in the OpenJPA interfaces used in Kodo. These conflicts arise because the OpenJPA interfaces extend the JPA interfaces that contain the methods that are revised in JPA 2.0.
These conflicts could cause problems with applications that use Kodo as the persistence provider, because the JPA 2.0 jar (rather than the JPA 1.0 jar) is on the WebLogic Server classpath.
To prevent these conflicts, two methods have been changed in the OpenJPA interfaces that ship with Kodo in WebLogic Server 12c and later. The OpenJPA methods that cause the conflict are:
public <T> T OpenJPAEntityManager.detach(T pc)
The above method conflicts with the following JPA 2.0 method in theEntityManager
interface:public void detach(Object)
public Properties OpenJPAEntityManagerFactory.getProperties()
The above method conflicts with the following JPA 2.0 method in theEntityManagerFactory
interface:public Map<String, Object> getProperties()
The new signatures are:
public <T> T OpenJPAEntityManager.detachCopy(T pc)
public Map<String, Object> OpenJPAEntityManagerFactory.getProperties()
public Properties OpenJPAEntityManagerFactory.getPropertiesAsProperties()
The first two new signatures follow the changes made in OpenJPA 2.x to address these same conflicts. These signature changes do not alter the semantics of the methods. The
getPropertiesAsProperties
method is provided as a convenience to application developers who do not want to accept the different return type of the redesigned getProperties
method. However, the method getPropertiesAsProperties
is not currently in the OpenJPA 2.x interface.Because of these changes, you should update any applications that use these methods and recompile them with the Kodo OpenJPA 1.0 jar (
org.apache.openjpa_
n
.jar
) and the JPA 1 jar (javax.persistence_
n
.jar
) that are shipped with WebLogic Server 12c (or later). This will prevent the old method signatures from being used. After recompiling and deploying, the applications will run without change in behavior.Applications that use Kodo/JDO are not affected by the conflicts described above. Therefore, you do not have to modify or recompile them.
Using a Newer Version of OpenJPA in Oracle WebLogic Server
The current release of OpenJPA from the Apache Foundation supports JPA 2, and you can use it as the persistence provider for applications deployed to WebLogic Server.
Note:
OpenJPA is a third-party library that you must plug into WebLogic Server. As such, Oracle support for Oracle WebLogic Server does not include support for the use of OpenJPA. These instructions are provided as a courtesy.To use the newer version of OpenJPA, do the following:
- Configure a filtering classloader to use the Kodo and OpenJPA classes, as follows:
- In a Web application, include the following stanza in the
weblogic.xml
file: - In an enterprise application, include the
prefer-application-packages
stanza inweblogic-application.xml
.)
For more information about filtering classloaders, see 'Using a Filtering Classloader' in Developing Applications for Oracle WebLogic Server. - Include the OpenJPA jar file in the application's
lib
directory. For more information about library directories, see 'Library Directories' in Developing Applications for Oracle WebLogic Server. - Configure the application to use OpenJPA (Kodo) as the provider. You cannot simply set Kodo as the domain's default provider in WebLogic Server. You must configure it in the application, as described in Specifying the Persistence Provider in an Application.
Note:
This last step applies for any JPA implementation that is packaged with an application. You must specify the implementation to use in the application code and not just accept the default set in WebLogic Server.