Using Oracle Kodo with WebLogic Server

Programming WebLogic Enterprise JavaBeans, Version 3.0

Using Oracle Kodo with WebLogic Server

This chapter provides an overview of developing, deploying, and configuring an Oracle Kodo application using WebLogic Server. The following topics are covered:

Overview of Kodo
Creating a Kodo Application
Using Different Kodo Versions
Configuring Persistence
Deploying a Kodo Application
Configuring a Kodo Application

Overview of Kodo

Oracle Kodo is an implementation of Sun Microsystem's 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 Servers overall Enterprise Java Bean 3.0 persistence implementation.
For general information on creating an application using JPA and JDO, see the Kodo Developer's Guide.

Creating a Kodo Application

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:

Oracle Kodo JPA Tutorials
Oracle Kodo JDO Tutorials

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.

Using Different Kodo Versions

If you choose to use a different version of Kodo than the one provided by default within WebLogic Server, use the FilteringClassLoader to exclude the Kodo and OpenJPA libraries from the component classpath.
The following example shows how to exclude these class libraries using weblogic-application.xml:
<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 With WebLogic Server.

Configuring Persistence

The following sections describe how to configure persistence.

Editing the Configuration Property Files
Using the Configuration Files Together
Configuring Plug-ins

Editing the Configuration Property Files

Oracle Kodo uses two XML files, listed in the following table, to define configuration properties.
Table 6-1 Persistence Configuration Files
Configuration File Description
persistence.xml Kodo configuration parameters defined by the JPA functional specifications. This file is required. The XML schema for structuring this configuration is available at: http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd. For more information, see “Chapter 6. Persistence” in the Kodo Developers Guide.
persistence-configuration.xml Configuration parameters that are specific to Oracle Kodo. This file is not required when deploying an application. If specified, still provide a persistence.xml descriptor. If you do not include persistence-configuration.xml in your deployment, WebLogic Server will create reasonable defaults for each configuration parameter. The XML schema for structuring this configuration is available at: http://www.bea.com/ns/weblogic/persistence-configuration.xsd.

The weblogic.jar file must be in the CLASSPATH when using the persistent-configuration.xml file in the Java SE environment.

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:

EJB-JAR file
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

Using the Configuration Files Together

The following provide considerations for using the configuration files together.

When using the persistence-configuration.xml file, all 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 Kodo persistence unit and provide advanced configuration and tunables support.
If 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.
If the persistence-configuration.xml descriptor is available and contains an entry for a given persistence unit, then no Kodo (kodo) or OpenJPA (openjpa) properties can be specified in the <properties> tag of the persistence.xml file for that persistence unit.

Configuring Plug-ins

Because Kodo is a highly customizable environment, many configuration properties relate to the creation and configuration of system plugins. Plugin properties have a syntax very similar to that of Java annotations. They allow you to specify both what class to use for the plugin and how to configure the public fields or bean properties of the instantiated plugin instance.
Essentially, plugins are defined using a series of properties using name/value pairs. For example, the following shows how a plugin is defined within persistence.xml:
<properties>

<property name='myplugin.DataCache' value='com.bea.MyDataCache(CacheSize=1000, RemoteHost='CacheServer)'>

</properties>
Deploying a Kodo Application

Before you deploy a Kodo application, perform the following tasks:

Create a Kodo application, as described in Creating a Kodo Application.
Configure persistence, as described in Configuring Persistence.
Created and archive for your application (.ear or .war).

Once completed, you are ready to deploy your application on WebLogic Server. Once your application is configured, a Kodo application is deployed just like any other application. For complete information on deploying applications, see Deploying Applications on Oracle WebLogic Server.

Configuring a Kodo Application

You cannot create a new persistence unit from the Administration Console. To create a new persistence unit, edit persistence.xml manually.
Once you have deployed your Kodo application, you can alter the configuration parameters defined in persistence.xml and persistence-configuration.xml.
The following sections describe how to configure a Kodo application with or without using the Administration Console.

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 Deployments
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 Kodo persistence parameters that can be edited from the Administration Console.

Configuring Kodo Without Using 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.xml and persistence-configuration.xml files that are archived with the application.
Use the 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 WebLogic Deployment.
Use the WLST loadApplication() method to load and update the application deployment plan. For more information, see “Updating the Deployment Plan” in 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 WebLogic Server.

Configuration File	Description
persistence.xml	Kodo configuration parameters defined by the JPA functional specifications. This file is required. The XML schema for structuring this configuration is available at: http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd. For more information, see “Chapter 6. Persistence” in the Kodo Developers Guide.
persistence-configuration.xml	Configuration parameters that are specific to Oracle Kodo. This file is not required when deploying an application. If specified, still provide a persistence.xml descriptor. If you do not include persistence-configuration.xml in your deployment, WebLogic Server will create reasonable defaults for each configuration parameter. The XML schema for structuring this configuration is available at: http://www.bea.com/ns/weblogic/persistence-configuration.xsd. The weblogic.jar file must be in the CLASSPATH when using the persistent-configuration.xml file in the Java SE environment.