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 kodo.jar in the beginning of the CLASSPATH .

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-persistence.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-persistence.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 and openjpa.jar into that same directory.

	Note
	JBoss currently ships with a stale version of the JPA specification jar. You should remove the old copy of this jar, ejb3-persistence.jar, from the server lib directory.

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 be deployed as a Java Connector Architecture (JCA) module or as shared application libraries. The sample user applications provided in the Kodo distribution demonstrate access patterns for both kinds of deployment.

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) and the OpenJPA jar (openjpa.jar) to the classpath so that your enhanced 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 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 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 kodo.jar in the beginning of the CLASSPATH.

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-persistence.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-persistence.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-persistence.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 and openjpa.jar files 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 kodo-jdo.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-jdo listed in the Connector Module. You have now installed Kodo JDO JCA.

Kodo persistence services can be deployed in servlet containers such as Apache Tomcat. The servlet or JSP based web applications running within the container can then use JPA or JDO services via javax.jdo.PersistenceManagerFactory or javax.persistence.EntityManagerFactory. The application can obtain reference to the factories using respective bootstrap methods javax.jdo.JDOHelper.getPersistenceManagerFactory() and javax.persistence.Persistence.createEntityManagerFactory().

The following example code demonstrates how to access the JDO PersistenceManagerFactory and subsequently a PersistenceManager:

    PersistenceManagerFactory pmf =
           JDOHelper.getPersistenceManagerFactory("kodo.properties");
    PersistenceManager pm = pmf.getPersistenceManager ();

The JDO configuration file name you specify must be available in the calling code's classpath. For example, package the file in WEB-INF/classes/kodo.properties of the web application archive.

The following code example demonstrates how to access the JPA EntityManagerFactory and EntityManager, where the JPA persistence unit configuration file is packaged in WEB-INF/classes/META-INF/persistence.xml and defines a persistence unit named "test":

    EntityManagerFactory emf =
         Persistence.createEntityManagerFactory("test");
    EntityManager em = emf.createEntityManager();

Web applications using Kodo can package Kodo libraries in the WEB-INF/lib directory of a WAR file or they can share the libraries with other web applications from a common location. To share the libraries, make them available to the common classloader of Tomcat by editing the $CATALINA_HOME/conf/catalina.properties file:

    common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,%KODO_ROOT%/lib/*.jar

	Note
	%KODO_ROOT% refers to the Kodo installation directory.

This makes all of the published Kodo libraries available to Tomcat, even though not all of the libraries are required.

To make only the required libraries available, you can include the following jar files in the WEB-INF/lib directory:

You may also include the above jars in the WEB-INF/lib directory of a deployable Web Application Archive. However, this restricts Kodo's availability to only the particular web application.

The samples/jdo/jsp directory contains an example of JSP based web application using Kodo JDO services to run a petshop. Use the following steps to run the samples in Tomcat. These steps require Apache Tomcat/6.0.10 installed and the homepage accessible at http://localhost:8080/:

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 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.

Note

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-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.

Kodo can be deployed as a Java Connector Architecture (JCA) module or as shared application libraries. The sample user applications provided in the Kodo distribution demonstrate access patterns for both kinds of deployment.