JPOX
JPOX
 JPOX Version 1.0
Configuration | Tutorials | Worked Examples | Developer
JPOX Tutorials
JPOX - Usage within a J2EE environment

The J2EE framework has become increasingly popular in the last 3 years. It provides a container within which java processes operate, and it provides mechanisms for, amongst other things, transactions (JTA), and for connecting to other (3rd party) utilities (using Java Connector Architecture, JCA). JPOX can be utilised within a J2EE environment via this JCA system, and we provide a Resource Adaptor (RAR file) containing this JCA adaptor allowing JPOX to be used with the likes of WebLogic and JBoss.

The provided JPOX JCA jar provides default resource adapter descriptors, one general, and the other for the WebLogic J2EE server. These resource adapter descriptors can be configured to meet your needs, for example allowing XA transactions instead of the default Local transactions.

Requirements

To use JPOX with JCA the first thing that you will require is the jpox-version.rar file (available from the download section).

General configuration

You then need to open the rar file and edit the /META-INF/ra.xml to set your database connection properties. Finally you close the RAR file with your changes. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE connector PUBLIC "-//Sun Microsystems, Inc.//DTD Connector 1.0//EN" "http://java.sun.com/dtd/connector_1_0.dtd">
<connector>
    <display-name>JPOX Connector</display-name>
    <description></description>
    <vendor-name>JPOX Team</vendor-name>
    <spec-version>1.0</spec-version>
    <eis-type>JDO Adaptor</eis-type>
    <version>1.0</version>
    <resourceadapter>
        <managedconnectionfactory-class>org.jpox.resource.ManagedConnectionFactoryImpl</managedconnectionfactory-class>
        <connectionfactory-interface>javax.resource.cci.ConnectionFactory</connectionfactory-interface>
        <connectionfactory-impl-class>org.jpox.resource.PersistenceManagerFactoryImpl</connectionfactory-impl-class>
        <connection-interface>javax.resource.cci.Connection</connection-interface>
        <connection-impl-class>org.jpox.resource.PersistenceManagerImpl</connection-impl-class>
        <transaction-support>LocalTransaction</transaction-support>
        <config-property>
          <config-property-name>ConnectionURL</config-property-name>
          <config-property-type>java.lang.String</config-property-type>
          <config-property-value>jpox:jdbc/ds</config-property-value>
        </config-property>
        <config-property>
          <config-property-name>ConnectionDriverName</config-property-name>
          <config-property-type>java.lang.String</config-property-type>
          <config-property-value>org.jpox.driver.JPOXDriver</config-property-value>
        </config-property>
        <config-property>
          <config-property-name>AutoCreateSchema</config-property-name>
          <config-property-type>boolean</config-property-type>
          <config-property-value>true</config-property-value>
        </config-property>
        <authentication-mechanism>
          <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
          <credential-interface>javax.resource.security.PasswordCredential</credential-interface>
        </authentication-mechanism>
        <reauthentication-support>false</reauthentication-support>
    </resourceadapter>
</connector>

The file shown above has a section for configuration properties. JPOX provides many, as described in the Runtime Configuration Guide. You can specify these via JCA. The table below shows the config property names and types.

config-property-nameconfig-property-typeconfig-property-value
ConnectionURLjava.lang.String
ConnectionDriverNamejava.lang.String
ConnectionUserNamejava.lang.String
ConnectionPasswordjava.lang.String
ConnectionFactoryNamejava.lang.String
ConnectionFactory2Namejava.lang.String
Multithreadedbooleantrue | false
Optimisticbooleantrue | false
RetainValuesbooleantrue | false
RestoreValuesbooleantrue | false
NontransactionalReadbooleantrue | false
NontransactionalWritebooleantrue | false
IgnoreCachebooleantrue | false
AutoCreateSchemabooleantrue | false
AutoCreateTablesbooleantrue | false
AutoCreateConstraintsbooleantrue | false
CheckExistTablesOrViewsbooleantrue | false
ValidateTablesbooleantrue | false
ValidateConstraintsbooleantrue | false
AutoStartMechanismjava.lang.StringSchemaTable | None
AutoStartMechanismModejava.lang.StringQuiet | Ignored | Checked
TransactionIsolationint
UseUpdateLockbooleantrue | false
StoreDictionaryCaseIdentifierjava.lang.String
DefaultSchemaNamejava.lang.String
FullyQualifiedNamesbooleantrue | false
MetadataFileExtensionjava.lang.Stringjdo
DelayDatastoreOperationsEnabledbooleantrue | false
PersistentIdGeneratorjava.lang.String
PoidTransactionIsolationLevelint
PoidTransactionAttributejava.lang.String
JdoInstancesCachePluginjava.lang.Stringorg.jpox.cache.WeakRefCache
JdoInstancesCacheGroupjava.lang.String
WebLogic

To use JPOX on Weblogic the first thing that you will require is the jpox-version.rar file. You then may need to edit the /META-INF/weblogic-ra.xml file to suit the exact version of your WebLogic server (the included file is for WebLogic 8.1).

You then deploy the RAR file on your WebLogic server.

JBoss

To use JPOX on JBoss (Ver 3.2) the first thing that you will require is the jpox-version.rar file. You should put this in the deploy ("${JBOSS}/server/default/deploy/") directory of your JBoss installation.

You then create a file, also in the deploy directory with name jpox-ds.xml. To give a guide on what this file will typically include, see the following 

<?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
    <tx-connection-factory>
        <jndi-name>jpox</jndi-name>
        <adapter-display-name>JPOX Connector</adapter-display-name>
        <config-property name="ConnectionDriverName" 
            type="java.lang.String">com.mysql.jdbc.Driver</config-property>
        <config-property name="ConnectionURL"
            type="java.lang.String">jdbc:mysql://localhost/yourdbname</config-property>
        <config-property name="UserName"
            type="java.lang.String">yourusername</config-property>
        <config-property name="Password"
            type="java.lang.String">yourpassword</config-property>
        <config-property name="AutoCreateSchema"
            type="boolean">true</config-property>
    </tx-connection-factory>
  
    <tx-connection-factory>
        <jndi-name>jpox1</jndi-name>
        <adapter-display-name>JPOX Connector</adapter-display-name>
        <config-property name="ConnectionDriverName"
            type="java.lang.String">com.mysql.jdbc.Driver</config-property>
        <config-property name="ConnectionURL"
            type="java.lang.String">jdbc:mysql://localhost/yourdbname1</config-property>
        <config-property name="UserName"
            type="java.lang.String">yourusername</config-property>
        <config-property name="Password"
            type="java.lang.String">yourpassword</config-property>
        <config-property name="AutoCreateSchema"
            type="boolean">true</config-property>
    </tx-connection-factory>
  
    <tx-connection-factory>
        <jndi-name>jpox2</jndi-name>
        <adapter-display-name>JPOX Connector</adapter-display-name>
        <config-property name="ConnectionDriverName"
            type="java.lang.String">com.mysql.jdbc.Driver</config-property>
        <config-property name="ConnectionURL"
            type="java.lang.String">jdbc:mysql://localhost/yourdbname2</config-property>
        <config-property name="UserName"
            type="java.lang.String">yourusername</config-property>
        <config-property name="Password"
            type="java.lang.String">yourpassword</config-property>
        <config-property name="AutoCreateSchema"
            type="boolean">true</config-property>
    </tx-connection-factory>
</connection-factories>

This example creates 3 connection factories to MySQL databases, but you can create as many or as few as you require for your system to whichever databases you prefer (as long as they are supported by JPOX). With the above definition we can then use the JNDI names java:/jpox, java:/jpox1, and java:/jpox2 to refer to our datastores.

You are now set to work on JPOX-enabling your actuall application. As we have said, you can use the above JNDI names to refer to the datastores, so you could do something like the following to access the PersistenceManagerFactory to one of your databases. 

import javax.jdo.PersistenceManagerFactory;

InitialContext            context=new InitialContext();
PersistenceManagerFactory pmFactory=
    (PersistenceManagerFactory)context.lookup("java:/jpox1");

These instructions were adapted from a HOWTO provided by a JPOX user (Marco Schulze) so thanks go to him for documenting his work and for sharing it. You can find the original instructions here.