Chapter 8. Deployment
Prev | Part 6. Kodo JPA/JDO Reference Guide | Next

## Chapter 8. Deployment

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.

## 8.1. Factory Deployment

Kodo offers several `EntityManagerFactory` and `PersistenceManagerFactory` deployment options.

### 8.1.1. Standalone Deployment

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 `org.apache.openjpa.persistence.OpenJPAPersistence` 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.

### 8.1.2. EntityManager Injection

Java EE 5 application servers allow you to inject entity managers into your session beans using the `PersistenceContext` annotation. See your application server documentation for details.

### 8.1.3. Kodo JPA JCA Deployment

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”

#### 8.1.3.1. WebLogic 9

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.

#### 8.1.3.2. JBoss 4.x

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, openjpa.jar and bea-licensing.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.

#### 8.1.3.3. Glassfish 9.1

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.

##### 8.1.3.3.1. Deploying as Connector Modules

The Kodo JCA Connector module for JPA is available in `jca/persistence/kodo-persistence.rar`. The JCA Connector module is configured in `META-INF/ra.xml` in `kodo-persistence.rar` archive file. The configuration file `ra.xml` must be edited for your environment before it can be deployed.

1. Go to the `%KODO_HOME%/jca/persistence` directory:

       $ cd %KODO_HOME%/jca/persistence

2. Extract `ra.xml`:

       $ jar xvf kodo-persistence.jar META-INF/ra.xml

3. With a text or XML editor, edit `META-INF/ra.xml` as follows:

   - Specify appropriate values for database connection properties namely `<ConnectionDriver>`, `<ConnectionURL>`, `<ConnectionUserName>`; and `<ConnectionPassword>` properties.

   - Specify `<value>buildSchema</value>` for `<SynchronizeMappings>` property. This setting ensures that Kodo will define the database schema for the persistent classes.

   - Specify `<value>` for the `<LicenseKey>` property.

4. The JCA Connector module will be bound to the JNDI tree of GlassFish. The JNDI name for the JCA connector is specified in the `sun-ra.xml` file. The Kodo distribution provides the `jca/persistence/sun-ra.xml` file, which specifies the JNDI name for JPA JCA Connector as `kodo-persistence`. You can edit `sun-ra.xml` to specify a different name. After making edits appropriate for your environment, update the `kodo-persistence.rar` archive with the edited version of `ra.xml` and `sun-ra.xml`, as follows:

       $ cp sun-ra.xml META-INF/sun-ra.xml

       $ jar uvf kodo-persistence.rar META-INF

5. Copy the following application libraries from `%KODO_HOME%/lib` to `%GLASSFISH%/lib`:

   - `bea-licensing.jar`

   - `commons-collections-3.2.jar`

   - `commons-lang-2.1.jar`

   - `commons-pool-1.3.jar`

   - `jpa.jar`

   - `openjpa.jar`

   - `serp.jar`

6. Start the GlassFish application server:

       					$ cd %GLASSFISH_HOME%/bin
       					$ asadmin -start-domain domain1

7. Deploy the JCA Connector module

       $ asadmin deploy %KODO_HOME%/jca/persistence/kodo-persistence.rar

   Or, if you prefer, open the GlassFish Administration Console in a browser. If you are running Glassfish on your local machine with the default configuration, the Administration Console is available at `http://localhost:4848/`. Activate `Connector Modules > Deploy` and select the file `%KODO_HOME%/jca/persistence/kodo-jar.rar`.

##### 8.1.3.3.2. Running the Samples

The Kodo distribution provides a set of samples to demonstrate usage within a J2EE Application Server. Some of the samples access Kodo persistence services by looking up JNDI for JCA Connector modules while others use the direct bootstrap API.

For both the JSP and EJB samples described below, perform the following step first:

Edit `META-INF/persistence.xml` and specify the appropriate values for these database connection properties: `ConnectionDriverName`, `ConnectionURL`, `ConnectionUserName`, and `ConnectionPassword`. Make sure these values are consistent with the setting in `META-INF/ra.xml` in `jca/persistence/kodo-persistence.rar`.

###### 8.1.3.3.2.1. EJB Samples Using JPA

This sample is available in `%KODO_HOME%/samples/persistence/j2ee`. It uses Kodo JPA by looking for the JPA JCA Connection module in JNDI. The sample also demonstrates the use of EJB 2.0 Beans using persistent classes. The steps to run the sample are presented in the `build.xml` Ant script.

Follow these instructions to run this sample:

1. Deploy the JPA JCA Connector module. The sample is configured for the HSQL database, and a JDBC driver is provided in `%KODO_HOME%/lib`. Copy the HSQL driver to `%GLASSFISH%/lib`. If you are using any other database, add the appropriate JDBC driver to `%GLASSFISH%/lib`.

2. Change to the `%KODO_HOME%/samples/persistence/j2ee directory`.

3. Ensure that the JNDI name in the `setSessionContext()` method in `ejb/CarBean.java` matches your JCA installation. This defaults to `java:/kodo-ejb`, but the actual value depends on the configuration of your JCA deployment and your application server's JNDI context. For example, the default name for a WebLogic 9 install would be simply `kodo-ejb`.

4. Compile the source files in place both in this base directory as well as the nested `ejb` and `jsp` directories:

       javac *.java  ejb/*.java jsp/*.java

5. Enhance the Car class:

       kodoc -p persistence.xml Car.java

6. Run the mapping tool; make sure that your `META-INF/persistence.xml` file includes the same connection information (e.g. Driver, URL, etc.) as your JCA installation, although note that when you deploy via JCA, the configuration information used at runtime will be the information provided in the JCA configuration file, not the `persistence.xml` file. You should update your JCA configuration to include `samples.persistence.j2ee.Car` in the `Types` parameter of the of the `MetaDataFactory` property:

       <config-property name="MetaDataFactory">Types=samples.persistence.j2ee.Car</config-property/>
       mappingtool -p persistence.xml Car.java

7. Build a J2EE application archive by running Ant against the `build.xml` file. This will `create kodo-persistence-j2ee-sample.ear`. This ear can now be deployed to your application server. Be sure to add the class `samples.j2ee.Car` to the `kodo.MetaDataFactory` Kodo configuration property. This will automatically register the Entity.

       ant -f build.xml

8. Deploy the enterprise application in GlassFish:

       $ cd %GLASSFISH%/bin
       $ asadmin deploy %KODO_HOME%/samples/persistence/j2ee/samplej2ee.ear

9. You can browse the running application at `http://<server>:<port>/samples/`.

#### 8.1.3.4. Kodo JDO JCA Deployment

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”

##### 8.1.3.4.1. WebLogic 6.1 to 7.x

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 `Persist`to 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">

##### 8.1.3.4.2. WebLogic 8.1

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

##### 8.1.3.4.3. WebLogic 9

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.

##### 8.1.3.4.4. JBoss 3.0

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.

##### 8.1.3.4.5. JBoss 3.2

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.

##### 8.1.3.4.6. JBoss 4.x

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.

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

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

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.rar`into 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.

##### 8.1.3.4.9. Tomcat

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 EWEB-INF/lib directory of a WATR file or they can share the libraries with other web applications from a common location. To share the libraries, make them available to the comman 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:

- commons-collections-3.2.jar

- commons-lang-2.1.jar

- commons-pool-1.3.jar

- jca1.0.jar

- jdbc-hsql-1_8_0.jar

- jdbc-mysql-3_0_14.jar

- jdo.jar

- jpa.jar

- jta-spec1_0_1.jar

- kodo-api.jar

- kodo-runtime.jar

- kodo.jar

- openjpa.jar

- serp.jar

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/`:

1. Edit `$CATALINA_HOME/conf/catalina.properties` as follows:

       common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,%KODO_ROOT%/lib/*.jar
       (%KODO_ROOT% is the Kodo installation directory)

2. Change directory to the Kodo installation directory.

3. Run the provided Ant script (`samples/jdo/jsp`) to compile and package the application:

       $ ant -f samples\jdo\jsp\build.xml

4. The Ant script creates a packaged web application named `petshop.war` in the `samples\jdo\jsp\` directory.

5. To deploy `petshop.war` in Tomcat, copy `petshop.war` to `$CATALINA_HOME/webapps` or deploy it using the browser-based Tomcat Manager (`http://localhost/manager/html/`).

6. Once `petshop.war` is deployed, go to `http://localhost/petshop/` to create and view animals.

##### 8.1.3.4.10. 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/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.

##### 8.1.3.4.11. Borland Enterprise Server 5.2 - 6.0

| Note
Borland includes two different `TransactionManager`s 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.

##### 8.1.3.4.12. Glassfish 9.1

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.

###### 8.1.3.4.12.1. Deploying as Connector Modules

The Kodo JCA Connector module for JDO is available in `jca/jdo/kodo-jdo.rar`. The JCA Connector module is configured in `META-INF/ra.xml` in `kodo-jdo.rar` archive file. The configuration file `ra.xml` must be edited for your environment before it can be deployed.

1. Go to the `%KODO_HOME%/jca/jdo` directory:

       $ cd %KODO_HOME%/jca/jdo

2. Extract `ra.xml`:

       $ jar xvf kodo-jdo.jar META-INF/ra.xml

3. With a text or XML editor, edit `META-INF/ra.xml` as follows:

   - Specify appropriate values for database connection properties namely `<ConnectionDriver>`, `<ConnectionURL>`, `<ConnectionUserName>`; and `<ConnectionPassword>` properties.

   - Specify `<value>buildSchema</value>` for the `<SynchronizeMappings>` property. This setting ensures that Kodo will define the database schema for the persistent classes.

   - Specify `<value>` for `<LicenseKey>` property.

4. The JCA Connector module will be bound to the JNDI tree of GlassFish. The JNDI name for the JCA connector is specified in the `sun-ra.xml` file. The Kodo distribution provides the `jca/jdo/sun-ra.xml` file, which specifies the JNDI name for JDO JCA Connector as `kodo-jdo`. You can edit `sun-ra.xml` to specify a different name. After making edits appropriate for your environment, update the `kodo-jdo.rar` archive with the edited version of `ra.xml` and `sun-ra.xml`, as follows:

       $ cp sun-ra.xml META-INF/sun-ra.xml

       $ jar uvf kodo-jdo.rar META-INF

5. Copy the following application libraries from `%KODO_HOME%/lib` to `%GLASSFISH%/lib`:

   - `bea-licensing.jar`

   - `commons-collections-3.2.jar`

   - `commons-lang-2.1.jar`

   - `commons-pool-1.3.jar`

   - `jdo.jar`

   - `openjpa.jar`

   - `serp.jar`

6. Start the GlassFish application server:

       					$ cd %GLASSFISH_HOME%/bin
       					$ asadmin -start-domain domain1

7. Deploy the JCA Connector module:

       $ asadmin deploy %KODO_HOME%/jca/jdo/kodo-jdo.rar

   Or, if you prefer, open the GlassFish Administration Console in a browser. If you are running Glassfish on your local machine with the default configuration, the Administration Console is available at `http://localhost:4848/`. Activate `Connector Modules > Deploy` and select the file `%KODO_HOME%/jca/jdo/kodo-jdo.rar`.

###### 8.1.3.4.12.2. Deploying as Application Libraries

Deploying Kodo as a shared library in GlassFish allows all applications to directly obtain a `javax.jdo.PersistenceManagerFactory` or `javax.persistence.EntityManagerFactory` via the bootstrap class `javax.jdo.JDOHelper or javax.persistence.Persistence`.

- bea-licensing.jar

- commons-collections-3.2.jar

- commons-lang-2.1.jar

- kodo-runtime.jar

- kodo-api.jar

- openjpa.jar

- serp.jar

- jdo.jar

- jpa.jar

###### 8.1.3.4.12.3. Running the Samples

The Kodo distribution provides a set of samples to demonstrate usage within a J2EE Application Server. Some of the samples access Kodo persistence services by looking up JNDI for JCA Connector modules while others use the direct bootstrap API.

For both the JSP and EJB samples described below, perform the following step first:

Edit `META-INF/jdo.properties` and specify the appropriate values for these database connection properties: `ConnectionDriverName`, `ConnectionURL`, `ConnectionUserName`, and `ConnectionPassword`. Make sure these values are consistent with the setting in `META-INF/ra.xml` in `jca/jdo/kodo-jdo.rar`.

###### 8.1.3.4.12.3.1. JSP Samples using JDO

This sample is available in the `%KODO_HOME%/samples/jdo/jsp` directory. This sample uses Kodo JDO by directly creating a `javax.jdo.PersistenceManagerFactory` via the `javax.jdo.JDOHelper.get PersistenceManagerFactory()` method. Hence, you can run this sample while you deploy Kodo in the shared application libraries of GlassFish. The steps to run the sample are presented in the `build.xml` Ant script.

Follow these instructions to run this sample:

1. Change to the `%KODO_HOME%/samples/jdo/jsp` directory:

       $ cd %KODO_HOME%/samples/jdo/jsp

2. Edit `petshop.properties` to add `LicenseKey` and database connection properties. The sample is configured for HSQL database, and a JDBC driver is provided in `%KODO_HOME%/lib`. Copy the HSQL driver to `%GLASSFISH%/lib`. If you are using any other database, add the appropriate JDBC driver to `%GLASSFISH%/lib` and edit the path to the driver JAR file in `<path id=compile.class.path>` in the `build.xml` file.

3. Run ant:

       $ ant

   This script compiles the classes, enhances the persistent classes, defines a database schema, and then packages the classes, JSP files, and configuration files into a Web Application Archive named `petshop.war`.

4. Deploy the web application in GlassFish:

       $ cd %GLASSFISH%/bin
       $ asadmin deploy %KODO_HOME%/samples/jdo/jsp/petshop.war

5. You can browse the running application at `http://<server>:<port>/petshop/`

###### 8.1.3.4.12.3.2. EJB Samples Using JDO

This sample is available in `%KODO_HOME%/samples/jdo/j2ee`. It uses Kodo JDO by looking for the JDO JCA Connection module in JNDI. The sample also demonstrates the use of EJB 2.0 Beans using persistent classes. The steps to run the sample are presented in the `build.xml` Ant script.

Follow these instructions to run this sample:

1. Deploy the JDO JCA Connector module. The sample is configured for the HSQL database, and a JDBC driver is provided in `%KODO_HOME%/lib`. Copy the HSQL driver to `%GLASSFISH%/lib`. If you are using any other database, add the appropriate JDBC driver to `%GLASSFISH%/lib`.

2. Change to the `%KODO_HOME%/samples/jdo/j2ee directory`.

3. If you deployed the JDO JCA Connector module with a name other than `kodo-jdo` by editing the corresponding `sun-ra.xml` file, then you must specify that name in the `pmf.jndi` property in `samples.properties`.

4. Compile the source files in place both in this base directory and in the nested `ejb` directory:

       javac *.java  ejb/*.java

5. Enhance the Car class.

       kodoc -p jdo.properties package.jdo

6. Run the mapping tool; make sure that your `META-INF/jdo.properties` file includes the same connection information (e.g. Driver, URL, etc.) as your installation:

       mappingtool -p jdo.properties package.jdo

7. Configure options in samples.properties to match your JCA installation, most notably the JNDI name to which you have bound Kodo (it defaults to `kodo`).

   | Warning
   This step (editing samples.properties) is very important as this value can be quite different for each appserver and each configuration. Be sure that the setting you put for `pmf.jndi` matches not only your configured setting but also what your application server may prefix the configured name with. Refer to your JNDI tree and the documentation for your application server for further details.

8. Build an J2EE application archive by running Ant against the `build.xml` file. This will create `samplej2ee.ear`. This ear can now be deployed to your application server.

       ant -f build.xml

9. Deploy the enterprise application in GlassFish:

       $ cd %GLASSFISH%/bin
       $ asadmin deploy %KODO_HOME%/samples/jdo/j2ee/samplej2ee.ear

10. You can browse the running application at `http://<server>:<port>/samples/`.

### 8.1.4. 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 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 ();

Prev | Up | Next
7.11. Orphaned Keys | Home | 8.2. Integrating with the Transaction Manager