4.3. Installing Kodo JCA

4.3.1. JBoss 3.0
4.3.2. JBoss 3.2
4.3.3. WebLogic 6.1 to 7.x
4.3.4. WebLogic 8.1
4.3.5. WebSphere 5
4.3.6. SunONE Application Server 7 / Sun Java Enterprise Server 8 - 8.1
4.3.7. Macromedia JRun 4
4.3.8. Borland Enterprise Server 5.2 - 6.0
4.3.9. Non-JCA Application Server Deployment

4.3.1. JBoss 3.0

The jca directory of the Kodo distribution includes kodo-service.xml. This file should be edited to reflect your configuration, most notably connection and license key values. Enter a JNDI name for Kodo to bind to (the default is kodo). Stop JBoss. Copy kodo.rar and kodo-service.xml to the deploy directory of your JBoss server installation (e.g. jboss-3.0.6/server/default/deploy ). Then copy the jdo-1.0.2.jar file to the lib directory of the JBoss server installation (e.g., jboss-3.0.6/server/lib/), so that the common JDO 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 (i.e. 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 kodo.jdbc.ee.JDBCConnectionFactory bound at the JNDI name you specified. You have now installed Kodo JCA.

4.3.2. JBoss 3.2

Installing in JBoss 3.2 is very similar to JBoss 3.0. Instead of editing and deploying kodo-service.xml, configuration is controlled by kodo-ds.xml, also in the jca 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-ds.xml and kodo.rar should be deployed to the deploy directory of JBoss. The installation is otherwise the same as JBoss 3.0.

4.3.3. WebLogic 6.1 to 7.x

Installation of Kodo into WebLogic requires 3 steps. First ensure that the appropriate JDBC driver is in the system classpath. In WebLogic 6.1.x, this should be 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-1.0.2.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.rar file should 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.rar and upload it to the server.

You should see kodo 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.rar) of the navigation pane. Select Persistto save your configuration properties and propgate 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 JCA.


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_1_0.dtd">

4.3.4. WebLogic 8.1


In its current version (8.1.0), there are a number of issues with classloaders in WebLogic's handling of EAR and RAR files. These instructions are aggressive in resolving potential issues which may no longer be issues in later releases of WebLogic.

First, ensure that your JDBC driver is in your system classpath. In addition, you will be adding jdo-1.0.2.jar to the system classpath. You can accomplish this by editing startWebLogic.sh/.cmd.

The next step is to deploy kodo.rar from the jca directory of your Kodo installation. Create a directory named kodo.rar in the applications directory of your domain. Un-jar kodo.rar into this new directory (without copying kodo.rar itself). Then extract kodo-jdo-runtime.jar in place and remove the file:

applications> mkdir kodo.rar
applications> cd kodo.rar
kodo.rar> jar -xvf /path/to/kodo.rar
kodo.rar> jar -xvf kodo-jdo-runtime.jar
kodo.rar> rm kodo-jdo-runtime.jar

Now you should configure Kodo JCA by editing META-INF/ra.xml substituing 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.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.

4.3.5. WebSphere 5

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.rar to the server. On the New page, enter a name for the new Kodo installation such as Kodo 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 JCA.

4.3.6. SunONE Application Server 7 / Sun Java Enterprise Server 8 - 8.1

Installation in SunONE / 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 SunONE / JES.

SunONE / JES requires a SunONE / JES-specific deployment file in addition to the generic ra.xml. Edit the sun-ra.xml file provided in the jca 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.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.rar META-INF/sun-ra.xml

Browse to the web admin console of SunONE / JES in your browser. Select your server under App Server Instances and expand to Applications/Connector Modules. Select Deploy and upload your new kodo.rar file. Enter an application name, and click the Select button. Apply your changes by selecting the link in the top right.


Unfortunately, SunONE / JES Application Server 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 kodo.rarinto a temporary directory. Edit ra.xml and provide your configuration values directly into the <config-property-value> elements into the proper <config-property> stanzas.

If you have installed Kodo correctly, you should see kodo listed in the Connector Module. You have now installed Kodo JCA.

4.3.7. Macromedia JRun 4

JRun requires a JRun-specific deployment file in addition to the generic ra.xml. Edit the jrun-ra.xml file provided in the jca 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.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.rar META-INF/jrun-ra.xml

Browse to the web admin console of JRun in your browser. Select your server in the servers tree andd expand to J2EE Components. Under Resource Adapters, select Add and upload your new kodo.rar file. The Kodo resource adapter will now be deployed to the JNDI name that you specified in the jrun-ra.xml file.


JRun does not provide any means of configuring a built-in DataSource that is not enlisted in a global transaction. This means that when configuing Kodo to use an external DataSource bound into JRun, you must also configure Kodo's Connection2URL, Connection2DriverName, Connection2UserName, and Connection2Password properties in order to provide Kodo with a nontransactional connection.

4.3.8. Borland Enterprise Server 5.2 - 6.0


Borland includes two different TransactionManagers for controlling the J2EE environment depending on your configuration. Kodo supports the standard instance on all versions of Borland. However, to use the two phase commit TransactionManager, labeled as the OTS service, you must use version 6.0 or higher. This is needed to support true XA transactions (prior versions had limited Java availability).

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.rar to a temporary directory:

mkdir tmp
cd tmp
jar -xvf ../kodo.rar 

From there, remove/move some jars that will cause class conflict issues with either your application or BES. Move jdo-1.0.2.jar to 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 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 .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-1.0.2.jar is added to 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 in your application as well as be visible in the JNDI viewer in the console. You have now installed Kodo JCA.

4.3.9. Non-JCA Application Server Deployment

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 dependant 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 4.1.  Binding a PersistenceManagerFactory into JNDI via a WebLogic Startup Class

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 JDBCPersistenceManagerFactory into JNDI.
public class StartKodo
    implements T3StartupDef
    private static final String PMF_JNDI_NAME  = "my.jndi.name";
    private static final String PMF_PROPERTY   = 
    private static final String PMF_CLASS_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;

        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 JDO can then obtain a handle to the PersistenceManagerFactory as follows:

Example 4.2. Looking up the PersistenceManagerFactory in JNDI

PersistenceManagerFactory factory = (PersistenceManagerFactory)
    new InitialContext ().lookup ("java:/MyKodoJNDIName");
PersistenceManager pm = factory.getPersistenceManager ();