4.3. Installing Kodo JCA
Prev | Chapter 4. J2EE Tutorial | Next

## 4.3. Installing Kodo JCA

### 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 `Persist`to 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.

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

### 4.3.4. 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 `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

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

SunONE requires a SunONE-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 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.

| Note
Unfortunately, SunONE 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.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` 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.

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

### 4.3.8. 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.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;

    /**
     * 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   =
            "javax.jdo.PersistenceManagerFactoryClass";
        private static final String PMF_CLASS_NAME =
            "kodo.jdbc.runtime.JDBCPersistenceManagerFactory";

        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);

            InitialContext ic = new InitialContext ();
            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 ();

Prev | Up | Next
4.2. J2EE Installation Types | Home | 4.4. Installing the J2EE Sample Application