Kodo Deprecation Notes:
Oracle Kodo JPA/JDO is deprecated in this release. Customers are encouraged to use Oracle TopLink, a JPA 2.0 provider. For more information about Oracle TopLink, see Chapter 8, "Configuring the Persistence Provider in Oracle WebLogic Server." Just as Kodo is deprecated, the Kodo documentation is also deprecated. For current information about using Kodo in WebLogic Server, see Using Oracle Kodo in Oracle WebLogic Server.
This release of WebLogic Server runs with the JPA 2.0 JAR in the server's classpath. Although JPA 2.0 is upwardly compatible with JPA 1.0, JPA 2.0 introduced some methods to existing JPA interfaces that conflict with existing signatures in OpenJPA interfaces. As a result, applications that continue to use Kodo/JPA as the persistence provider with WebLogic Server 12.1.1 must be recompiled. For more information, see Updating Applications to Overcome Conflicts with JPA 2.0.
Kodo does not support JPA 2.0. Trying to used JPA 2.0 APIs with Kodo in WebLogic Server will produce an error. However, using Kodo as the persistence provider for a specific persistence unit or as the default provider for the domain does not prevent you from using TopLink for a different persistence unit. For more information, see Using Oracle Kodo in Oracle WebLogic Server.
Oracle Kodo is an implementation of the Java Persistence API (JPA) specification and Java Data Objects (JDO) specification for transparent data objects. Oracle Kodo is available as a stand-alone product and is integrated within WebLogic Server.
This chapter describes how to implement an application using JPA or JDO in WebLogic Server. Within WebLogic Server, the JPA and JDO implementations are part of WebLogic Server's overall Enterprise JavaBean 3.0 persistence implementation.
For general information on creating an application using JPA and JDO, see the Kodo 4.2.0 Developers Guide for JPA/JDO.
The first step in implementing a Oracle Kodo application on WebLogic Server is to write the application code. The following resources provide general information on writing an application that uses Oracle Kodo to manage persistence of your data:
Once you are familiar with the steps involved in creating applications using Oracle Kodo and have created your application, the following sections describe how to deploy and configure your application using WebLogic Server.
If you choose to use a different version of Oracle Kodo than the one provided by default within WebLogic Server, you must use the
FilteringClassLoader to specify the packages—in this case Oracle Kodo and OpenJPA— that you want to be loaded from the application, and not from the system classloader.
The following example shows how to load the Oracle Kodo and OpenJPA packages from the application using
<prefer-application-packages> <package-name>org.apache.openjpa.*</package-name> <package-name>kodo.*</package-name> </prefer-application-packages>
For more information on filtering classloaders, see "Understanding WebLogic Server Application Classloading" in Developing Applications for Oracle WebLogic Server.
Then, you can package the Oracle Kodo and OpenJPA packages with your application using the library directory, as described in "Library Directories" in Developing Applications for Oracle WebLogic Server.
The following sections describe how to configure persistence.
Oracle Kodo uses two XML files, listed in the following table, to define configuration properties.
Oracle Kodo configuration parameters defined by the JPA functional specifications. This file is required.
The XML schema for structuring this configuration is available at:
Configuration parameters that are specific to Oracle Kodo. This file is not required when deploying an application. If specified, you must still provide a
If you do not include
The XML schema for structuring this configuration is available at:
Edit the contents of the configuration files as required to configure persistence. Persistence units can be packaged as part of a WAR or EJB JAR file, or can be packaged as a JAR file that can be included in a WAR or EAR file. The files should be available as resources in the
META-INF directory of the root of the persistence unit. For container environments, the root of a persistence unit may be one of the following:
WEB-INF/classes directory of a WAR file
JAR file in the
WEB-INF/lib directory of a WAR file
JAR file in the root of the EAR
JAR file in the EAR library directory
Application client jar file
The following provide considerations for using the configuration files together.
When using the
persistence-configuration.xml file, all Oracle Kodo-specific properties must be included in the
persistence-configuration.xml file and not the
persistence.xml file. In this case, the WebLogic Server Administration Console and WebLogic Scripting Tool (WLST) recognizes the persistence unit as a Oracle Kodo persistence unit and provide advanced configuration and tunables support.
If Oracle Kodo-specific properties are included in the
persistence.xml file, the persistence unit will be treated as a third-party persistence unit by the Administration Console and WLST.
persistence-configuration.xml descriptor is available and contains an entry for a given persistence unit, then no Oracle Kodo (
kodo) or OpenJPA (
openjpa) properties can be specified in the
<properties> tag of the
persistence.xml file for that persistence unit.
Because Oracle Kodo is a highly customizable environment, many configuration properties relate to the creation and configuration of system plug-ins. Plug-in properties have a syntax very similar to that of Java annotations. They allow you to specify both what class to use for the plug-in and how to configure the public fields or bean properties of the instantiated plug-in instance.
Essentially, plug-ins are defined using a series of properties using name/value pairs. For example, the following shows how a plug-in is defined within
<properties> <property name='myplugin.DataCache' value='com.bea.MyDataCache(CacheSize=1000, RemoteHost='CacheServer)'> </properties>
Before you deploy a Oracle Kodo application, you must perform the following tasks:
Create a Oracle Kodo application, as described in Creating an Oracle Kodo Application.
Configure persistence, as described in Configuring Persistence.
Created an archive for your application (
Once completed, you are ready to deploy your application on WebLogic Server. Once your application is configured, an Oracle Kodo application is deployed just like any other application. For complete information on deploying applications, see Deploying Applications to Oracle WebLogic Server.
You cannot create a new persistence unit from the Administration Console. To create a new persistence unit, you must edit
Once you have deployed your Oracle Kodo application, you can alter the configuration parameters defined in
The following sections describe how to configure a Oracle Kodo application with or without using the Administration Console.
If your deployed application has defined a persistence unit within
persistence.xml, you can access configuration from within the Administration Console using the following:
Select the name of the module containing a persistence unit that you want to configure.
Select the Configuration tab.
Select the Persistence tab.
From the list of persistence units, select the one that you want to configure.
From here, you can access all of the Oracle Kodo persistence parameters that can be edited from the Administration Console.
If you need to alter parameters that are not available using the Administration Console, use one of the following methods:
Manually edit the
persistence-configuration.xml files that are archived with the application.
SessionHelper to access and configure the deployment plan. For more information, see "SessionHelper" in "The Tools Package" in "Understanding the WebLogic Deployment API" in Programming Deployment for Oracle WebLogic Server.
Use the WLST
loadApplication() method to load and update the application deployment plan. For more information, see "Updating the Deployment Plan" in Oracle WebLogic Scripting Tool.
Manually edit your deployment plan. For more information, see "Manually Customizing the Deployment Plan" in "Exporting an Application for Deployment to New Environments" in Deploying Applications to Oracle WebLogic Server.