Kodo deployment includes choosing a factory deployment strategy, and in a managed environment, optionally integrating with your application server's managed and XA transactions. This chapter examines each aspect of deployment in turn.
Kodo offers several
EntityManagerFactory
and
PersistenceManagerFactory
deployment options.
The JPA Overview describes the
javax.persistence.Persistence class. You
can use Persistence to obtain
EntityManagerFactory instances, as
demonstrated in Chapter 6, Persistence.
Kodo also extends Persistence to add
additional EntityManagerFactory
creation methods. The
kodo.persistence.KodoPersistence class
Javadoc details these extensions.
Chapter 6, JDOHelper of the JDO Overview
describes the JDOHelper class.
Section 6.3, “PersistenceManagerFactory Construction” shows how to use
the JDOHelper to construct
PersistenceManagerFactory objects
in a vendor-neutral fashion.
After obtaining the factory, you can cache it for all
EntityManager
or
PersistenceManager
creation duties.
Kodo can deploy Kodo JPA through the Java Connector Architecture (JCA) in any JCA-compliant application server that supports JDK 1.5 (all EJB 3 implementations require JDK 1.5). We present the deployment steps for the most common servers below.
Be sure to have your BEA license file available to the system classpath as detailed in Section 2.2, “License Configuration”
First, ensure that your JDBC driver is in your system classpath.
In addition, you will be adding the Kodo and specification API
jars to the system classpath. You can accomplish this by
editing startWebLogic.sh/.cmd.
![[Warning]](img/warning.gif) | Warning |
|---|---|
Currently WebLogic ships with an old version
of the EJB 3 libraries. Be sure to put
|
The next step is to deploy
kodo-persistence.rar from the
jca/persistence directory of your Kodo
installation. Copy this file to the autodeploy
directory of your domain.
We will now extract META-INF/ra.xml
and META-INF/weblogic-ra.xml
to edit our configuration:
jar xvf kodo-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml
Now you should configure Kodo JCA by editing
META-INF/ra.xml substituting
config-property-value stanzas
with your own values. You can comment out
properties (config-property stanzas) which you are
not using or you can leave them at their default settings.
Edit META-INF/weblogic-ra.xml
to configure the JNDI location to which you
want Kodo to be bound.
Now we can re-jar the manifest files back into the
RAR file.
jar uvf kodo-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml rm META-INF/ra.xml META-IN/weblogic-ra.xml rmdir META-INF
Now you can start WebLogic and WebLogic should deploy Kodo for you. If you have installed Kodo correctly, at this point, one should be able to see Kodo bound to the JNDI location which you specified earlier.
First you must add the JPA specification jar,
jpa.jar, which is found in the
lib directory of the disribution,
to the server library directory: e.g.
jboss-4.0.3/server/default/lib).
In addition, you should also place the appropriate JDBC
driver jar into that same directory.
![[Note]](img/note.gif) | Note |
|---|---|
JBoss currently ships with a stale version of the
JPA specification jar. You should remove the
old copy of this jar,
|
The jca/persistence directory of the Kodo
distribution includes
kodo-persistence-jboss40-ds.xml. This file
should be edited to reflect your configuration, most notably
connection values. Enter a JNDI name for Kodo
to bind to (the default is kodo-persistence).
Stop JBoss. Copy kodo-persistence.rar and
kodo-ejb-jboss40-ds.xml to the deploy
directory of your JBoss server installation (e.g.
jboss-4.0.3/server/default/deploy). Once you
have done this, you can restart JBoss to deploy Kodo.
To verify your installation, watch the console output for
exceptions. In addition, you can check to see if Kodo was
bound to JNDI. Open up your jmx-console (
http://yourhost:yourport/jmx-console) and
select the JNDIView service. If Kodo was installed correctly,
you should see the Kodo connection factory bound at the JNDI
name you specified. You have now installed Kodo JPA JCA.
Kodo can deploy through the Java Connector Architecture (JCA) in any JCA-compliant application server. We present the deployment steps for the most common servers below.
Be sure to have your BEA license file available to the system classpath as detailed in Section 2.2, “License Configuration”
Installation of Kodo into WebLogic requires 3 steps. First
ensure that Kodo jars, the specification jars, and the
appropriate JDBC driver are in the system
classpath. In WebLogic 6.1.x, the classpath is set in the
startWebLogic.sh/cmd in your domain
directory ($WL_HOME/config/mydomain). In
WebLogic 7, this file is the startWLS.sh/cmd
file in the $WL_HOME/server/bin
directory.
Make sure to also add the JDO base jar
(jdo.jar) to the classpath so that
your JDO classes can be loaded. While this jar can be placed
inside an ear file, putting
it in the system classpath will reduce class resolution
conflicts.
The kodo-jdo.rar file must then either
be copied to the applications directory of your domain,
or uploaded through the web admin interface. To upload using
the web admin console, select
mydomain/Deployments/Connectors
in the left navigation bar and then select "Install a new
Connector Component." Browse to
kodo-jdo.rar
and upload it to the server.
You should see kodo-jdo listed
now in the Connectors folder in the
navigation pane. Select it and select
Edit Connector Descriptor.
Under RA,
expand Config Properties in
the left pane and enter the appropriate values for each
property. Be sure to select Apply
for every property. In addition,
you should provide a JNDI name for Kodo by selecting
Weblogic RA from the
navigation panel, entering an appropriate JNDI name, and
selecting Apply. When you
are done configuring Kodo,
select the root (kodo-jdo.rar) of the navigation pane. Select
Persistto save your
configuration properties and propagate them to the active
domain configuration.
You should see WebLogic attempt to deploy Kodo in the system
console. When it is done, return to the main admin web console.
Ensure that Kodo is deployed to your server by selecting
Targets and adding your server
to the chosen area. Kodo should now be deployed to your
application server.
To verify the installation, you can view the JNDI tree
for your server. Select the server from the admin
navigation panel, right click on it, and select
View JNDI Tree from the context menu.
You should now see Kodo at the JNDI name you provided. You
have now installed Kodo JDO JCA.
| Note |
|---|---|
When using WebLogic 7, you may get invalid DTD exceptions when loading JDO metadata files, due to a problem with loading resources that are in jar files inside a resource archive. You can work around these problems by specifying a non-public DTD in your metadata files, like so: <!DOCTYPE jdo SYSTEM "http://java.sun.com/dtd/jdo_2_0.dtd"> |
| Note |
|---|---|
In its current version (8.1.0), there are a number
of issues with classloaders in WebLogic's handling
of |
First, ensure that your JDBC driver is in your system classpath.
In addition, you will be adding the Kodo and specification API
jars to the system classpath. You can accomplish this by
editing startWebLogic.sh/.cmd.
The next step is to deploy kodo-jdo.rar
from the jca/jdo directory of your Kodo
installation. Create a directory named kodo-jdo.rar
in the applications directory
of your domain. Un-jar kodo-jdo.rar
into this new directory (without copying kodo-jdo.rar itself).
Now you should configure Kodo JCA by editing
META-INF/ra.xml substituting
config-property-value stanzas
with your own values. You can comment out
properties (config-property stanzas) which you are
not using or leaving at default settings.
Edit META-INF/weblogic-ra.xml
to configure the JNDI location to which you
want Kodo to be bound.
Now you can start WebLogic and use the
console to deploy Kodo JCA. Browse
to your WebLogic admin port (http://yourhost:7001/console)
and browse to the Connectors
(Deployments -> Connector Modules) section
and select Deploy a new Connector.
Browse to and select kodo-jdo.rar
and select Target Modules to
ensure that Kodo is accessible to the proper servers.
If you have installed Kodo correctly, at this point, one should be able to see Kodo bound to the JNDI location which you specified earlier.
First, ensure that your JDBC driver is in your system classpath.
In addition, you will be adding the Kodo and specification API
jars to the system classpath. You can accomplish this by
editing startWebLogic.sh/.cmd.
| Warning |
|---|---|
Currently WebLogic ships with an old version
of the EJB 3 libraries. Be sure to put
|
The next step is to deploy the RAR
appropriate to the default specification you want to use.
For example, to default to JPA, copy kodo-ejb.rar
from the jca/ejb directory
to the autodeploy directory
of your domain.
We will now extract META-INF/ra.xml
and META-INF/weblogic-ra.xml
to edit our configuration:
jar xvf kodo-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml
Now you should configure Kodo JCA by editing
META-INF/ra.xml substituting
config-property-value stanzas
with your own values. You can comment out
properties (config-property stanzas) which you are
not using or leaving at default settings.
Edit META-INF/weblogic-ra.xml
to configure the JNDI location to which you
want Kodo to be bound.
Now we can re-jar the manifest files back into the
RAR file.
jar uvf kodo-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml rm META-INF/ra.xml META-IN/weblogic-ra.xml rmdir META-INF
Now you can start WebLogic and WebLogic should deploy Kodo for you. If you have installed Kodo correctly, at this point, one should be able to see Kodo bound to the JNDI location which you specified earlier.
The jca/jdo directory of the Kodo
distribution includes
kodo-jdo-jboss30-service.xml. This file
should be edited to reflect your configuration, most notably
connection values. Enter a JNDI name for Kodo
to bind to (the default is kodo-jdo). Stop
JBoss. Copy kodo-jdo.rar and
kodo-jdo-jboss30-service.xml to the deploy
directory of your JBoss server installation (e.g.
jboss-3.0.6/server/default/deploy). Then copy the
jdo.jar file to the lib directory of
the JBoss server installation (e.g.,
jboss-3.0.6/server/lib/), so that the
Kodo and the common specification APIs are available globally
in the JBoss installation. In addition, you should also place
the appropriate JDBC driver jar in the lib directory of your
JBoss installation (e.g. jboss-3.0.6/lib).
To verify your installation, watch the console output for
exceptions. In addition, you can check to see if Kodo was
bound to JNDI. Open up your jmx-console (
http://yourhost:yourport/jmx-console) and
select the JNDIView service. If Kodo was installed correctly,
you should see the Kodo connection factory bound at the JNDI
name you specified. You have now installed Kodo JDO JCA.
Installing in JBoss 3.2 is very similar to JBoss 3.0.
Instead of editing and deploying
kodo-jdo-jboss30-service.xml, configuration
is controlled by kodo-jdo-jboss32-ds.xml,
also in the jca/jdo directory. Again,
configuration involves supplying a JNDI name to bind Kodo, and
setting up configuration values. These values are simple XML
elements with the configuration property name as element name.
kodo-jdo-jboss32-ds.xml and
kodo-jdo.rar should be deployed to the
deploy directory of JBoss. The installation is otherwise the
same as JBoss 3.0.
Installing in JBoss 4.x is very similar to JBoss 3.0 and 3.2.
Instead of editing and deploying
kodo-jdo-jboss30-service.xml, configuration
is controlled by kodo-jdo-jboss40-ds.xml,
also in the jca/jdo directory. Again,
configuration involves supplying a JNDI name to bind Kodo, and
setting up configuration values. These values are simple XML
elements with the configuration property name as element name.
kodo-jdo-jboss4-ds.xml and
kodo-jdo.rar should be deployed to the
deploy directory of JBoss. The installation is otherwise the
same as JBoss 3.0.
Websphere installation is easiest through the web admin
interface. Open the admin console either by the Start
menu item (in Windows), or by manually navigating to
the admin port and URL appropriate to your installation. Select
Resources / Resource Adapters
from the left navigation panel. Select
Install Rar on the list page. On the
following screen upload kodo-jdo.rar to the
server. On the New page,
enter a name for the new Kodo installation such as Kodo JDO JCA
and select Ok.
You should now be back to the Resource Adapters list page.
Select the name of the Kodo installation you provided. Click
on the link marked J2C Connection
Factories. This is where you can configure a
particular instance of Kodo's JCA implementation. Select
New and you will be brought to
a configuration page. Be sure to fill in property
values for Name and JNDI Name. Select
Apply.
After the page refreshes, select the Custom
Properties link at the bottom of the page.
On the Custom Properties page,
you can enter in your connection and other configuration
properties as necessary.
When you are done providing configuration values, you will
want to save your changes back to the system configuration.
Select the Save link on the
page or the Save link in the
menu bar. You have now installed Kodo JDO JCA.
Installation in SunONE / Sun JES application server requires
first providing JDO the proper permissions. This is
accomplished by editing the config/server.policy
for the server you are dealing with. Edit the
file to include the following line into a grant { } stanza.
permission javax.jdo.spi.JDOPermission "*";
Now restart the application server.
SunONE / Sun JES requires a Sun-specific deployment file in
addition to the generic ra.xml. Edit the
sun-ra.xml file provided in the
jca/jdo directory of your Kodo installation
by setting
jndi-name attribute to the JNDI name of your
choice. Then add <property> elements
that correspond to the <config-property-name>
in ra.xml to configure
connection info and other configuration elements. Now update
kodo-jdo.rar to include
sun-ra.xml in the
META-INF virtual directory in the archive:
mkdir META-INF copy sun-ra.xml META-INF jar -uvf kodo-jdo.rar META-INF/sun-ra.xml
Browse to the web admin console of SunONE / Sun JES in your
browser. Select your server under App Server
Instances and expand to
Applications/Connector Modules.
Select Deploy and upload your
new kodo-jdo.rar file. Enter an
application name, and click the
Select button. Apply your
changes by selecting the link in the top right.
| Note |
|---|---|
Unfortunately, SunONE / Sun JES sometimes may not
accept its own configuration file format. If this is the
case, you will see exceptions as if your configuration
values had not been set at all. To bypass this problem,
extract |
If you have installed Kodo correctly, you should see
kodo-jdo listed in the
Connector Module.
You have now installed Kodo JDO JCA.
JRun requires a JRun-specific deployment file in addition to
the generic ra.xml. Edit the
jrun-ra.xml file provided in the
jca/jdo directory of your Kodo installation
by setting
jndi-name attribute to the JNDI name of your
choice. Then add <property> elements
that correspond to the <config-property-name>
in ra.xml to configure
connection info and other configuration elements. Now update
kodo-jdo.rar to include
jrun-ra.xml in the
META-INF virtual directory in the archive:
mkdir META-INF copy jrun-ra.xml META-INF jar -uvf kodo-jdo.rar META-INF/jrun-ra.xml
Browse to the web admin console of JRun in your browser.
Select your server in the servers tree
and expand to J2EE Components.
Under Resource Adapters,
select Add and upload your new
kodo-jdo.rar file. The Kodo resource
adapter
will now be deployed to the JNDI name that you specified in
the jrun-ra.xml file.
| Note |
|---|---|
JRun does not provide any means of configuring a built-in
|
| Note |
|---|---|
Borland includes two different
|
Due to classloader issues, as well as configuration of the RAR itself, some basic expertise in jar and unjarring is required to install Kodo into BES. Otherwise, we recommend deploying Kodo, then switching to single classpath for the entire system through the Admin tool (which prevents hot deploy) to ease classpath conflict issues. First extract kodo-jdo.rar to a temporary directory:
mkdir tmp cd tmp jar -xvf ../kodo-jdo.rar
From there, remove/move some jars that will cause class conflict
issues with either your application or BES.
Next, add the JDO specification API jars
and your JDBC driver jars into the system classpath
(e.g.
var/servers/your_server/partitions/lib/system).
You must configure the RAR by editing the
ra-borland.xml file included in
the jca/jdo directory of your Kodo
installation. Move this file into the
META-INF directory
of the expanded RAR file. Refer to the DTD and Borland's
documentation on advanced features of the deployment descriptor,
including deployment and security options.
With this completed, you can re-jar the expanded contents
into a new kodo-bes.rar file to be deployed
using iastool or the console interface. Before deploying,
first enable Visiconnect on the
partition using the console or the command-line utilities.
This will activate JCA support in the application server.
Then restart BES so that Visiconnect can activate and
so that jdo.jar is added to the runtime classpath
the runtime classpath. When deploying, stubs and verification
do not need to be processed on the file and may simplify
the deployment process.
tmp> jar -cvf kodo-bes.rar *
After a restart, Kodo should now be deployed to BES. You should be able to find Kodo at the JNDI location of serial://kodo-jdo in your application as well as be visible in the JNDI viewer in the console. You have now installed Kodo JDO JCA.
For application servers that do not support JCA as a means
of deploying resource adapters, Kodo can be deployed manually
by writing some code to configure and bind an instance of the
PersistenceManagerFactory into JNDI.
The mechanism by which you do this is up to you and will be dependent on functionality that is specific to your application server. The most common way is to create a startup class according to your application server's documentation that will create a factory and then bind it in JNDI. For example, in WebLogic you could write a startup class as follows:
Example 8.1. Binding a Factory into JNDI via a WebLogic Startup Class
JPA:
import java.util.*;
import javax.naming.*;
import weblogic.common.T3ServicesDef;
import weblogic.common.T3StartupDef;
import weblogic.jndi.WLContext;
/**
* This startup class creates and binds an instance of a
* Kodo EntityManagerFactory into JNDI.
*/
public class StartKodo
implements T3StartupDef
{
private static final String EMF_JNDI_NAME = "my.jndi.name";
private T3ServicesDef services;
public void setServices (T3ServicesDef services)
{
this.services = services;
}
public String startup (String name, Hashtable args)
throws Exception
{
String jndi = (String) args.get ("jndiname");
if (jndi == null || jndi.length () == 0)
jndi = PMF_JNDI_NAME;
EntityManagerFactory factory = Persistence.createEntityManagerFactory
("name of entity manager in META-INF/persistence.xml");
Hashtable icprops = new Hashtable ();
icprops.put (WLContext.REPLICATE_BINDINGS, "false");
InitialContext ic = new InitialContext (icprops);
ic.bind (jndi, factory);
// return a message for logging
return "Bound EntityManagerFactory to " + jndi;
}
}
JDO:
import java.util.*;
import javax.naming.*;
import weblogic.common.T3ServicesDef;
import weblogic.common.T3StartupDef;
import weblogic.jndi.WLContext;
/**
* This startup class creates and binds an instance of a
* Kodo PersistenceManagerFactory into JNDI.
*/
public class StartKodo
implements T3StartupDef
{
private static final String PMF_JNDI_NAME = "my.jndi.name";
private static final String PMF_PROPERTY =
"javax.jdo.PersistenceManagerFactoryClass";
private static final String PMF_CLASS_NAME =
"kodo.jdo.PersistenceManagerFactoryImpl";
private T3ServicesDef services;
public void setServices (T3ServicesDef services)
{
this.services = services;
}
public String startup (String name, Hashtable args)
throws Exception
{
String jndi = (String) args.get ("jndiname");
if (jndi == null || jndi.length () == 0)
jndi = PMF_JNDI_NAME;
Properties props = new Properties ();
props.setProperty (PMF_PROPERTY, PMF_CLASS_NAME);
// you could set additional properties here; otherwise, the defaults
// from kodo.properties will be used (if the file exists)
PersistenceManagerFactory factory = JDOHelper.
getPersistenceManagerFactory (props);
Hashtable icprops = new Hashtable ();
icprops.put (WLContext.REPLICATE_BINDINGS, "false");
InitialContext ic = new InitialContext (icprops);
ic.bind (jndi, factory);
// return a message for logging
return "Bound PersistenceManagerFactory to " + jndi;
}
}
Applications that utilize Kodo can then obtain a handle to the factory as follows:
Example 8.2. Looking up the Factory in JNDI
JPA:
EntityManagerFactory factory = (EntityManagerFactory)
PortableRemoteObject.narrow (EntityManagerFactory.class,
new InitialContext ().lookup ("java:/MyKodoJNDIName"));
EntityManager em = factory.getEntityManager ();
JDO:
PersistenceManagerFactory factory = (PersistenceManagerFactory)
PortableRemoteObject.narrow (PersistenceManagerFactory.class,
new InitialContext ().lookup ("java:/MyKodoJNDIName"));
PersistenceManager pm = factory.getPersistenceManager ();
