Java Persistent Objects - JPOX Auto-Start

By default with JDO implementations when you open a PersistenceManagerFactory and obtain a PersistenceManager JPOX knows nothing about which classes are to be persisted to that datastore. JDO implementations only load the Meta-Data for any class when the class is first enlisted in a PersistenceManager operation. For example you call makePersistent on an object. The first time a particular class is encountered JPOX will dynamically load the Meta-Data for that class. This typically works well since in an application in a particular operation the PersistenceManagerFactory may well not encounter all classes that are persistable to that datastore. The reason for this dynamic loading is that JDO implementations can't be expected to scan through the whole Java CLASSPATH for classes that could be persisted there. That would be inefficient.

There are situations however where it is desirable for JPOX to have knowledge about what is to be persisted, so that it can load the Meta-Data at initialisation of the persistence factory and hence when the classes are encountered for the first time nothing needs doing. This JPOX extension is known as Auto-Start Mechanism. This is set with the property org.jpox.autoStartMechanism. This can be set to None, XML, Classes or SchemaTable. These are described below.

None

With this property set to "None" JPOX will have no knowledge about classes that are to be persisted into that datastore and so will add the classes when the user utilises them in calls to the various PersistenceManager methods.

XML

With XML, JPOX stores the information for starting up JPOX in an XML file. This is, by default, located in jpoxAutoStart.xml in the current working directory. The file name can be configured using the persistence factory property org.jpox.autoStartMechanismXmlFile. The file is read at startup and JPOX loads the classes using this information.

If the user changes their persistence definition a problem can occur when starting up JPOX. JPOX loads up its existing data from the XML configuration file and finds that a table/class required by the this file data no longer exists. There are 3 options for what JPOX will do in this situation. The property org.jpox.autoStartMechanismMode defines the behaviour of JPOX for this situation.

Checked will mean that JPOX will throw an exception and the user will be expected to manually fix their database mismatch (perhaps by removing the existing tables).
Quiet (the default) will simply remove the entry from the XML file and continue without exception.
Ignored will simply continue without doing anything.

Classes

With Classes, the user provides to the persistence factory the list of classes to use as the initial list of classes to be persisted. They specify this via the persistence property org.jpox.autoStartClassNames, specifying the list of classes as comma-separated. This gives JPOX a head start meaning that it will not need to "discover" these classes later.

SchemaTable

When using an RDBMS datastore the SchemaTable auto-start mechanism stores the list of classes (and their tables, types and version of JPOX) in a datastore table JPOX_TABLES. This table is read at startup of JPOX, and provides JPOX with the necessary knowledge it needs to continue persisting these classes. This table is continuously updated during a session of a JPOX-enabled application. This is the default setting for the auto-start mechanism so, unless you change the org.jpox.autoStartMechanism property, you will have a table JPOX_TABLES created in your datastore schema.

If the user changes their persistence definition a problem can occur when starting up JPOX. JPOX loads up its existing data from JPOX_TABLES and finds that a table/class required by the JPOX_TABLES data no longer exists. There are 3 options for what JPOX will do in this situation. The property org.jpox.autoStartMechanismMode defines the behaviour of JPOX for this situation.

Checked will mean that JPOX will throw an exception and the user will be expected to manually fix their database mismatch (perhaps by removing the existing tables).
Quiet (the default) will simply remove the entry from JPOX_TABLES and continue without exception.
Ignored will simply continue without doing anything.

The default database schema used the SchemaTable is described below:

TABLE  : JPOX_TABLES
(
COLUMN : CLASS_NAME VARCHAR(128) PRIMARY KEY,  -- Fully qualified persistent Class name
COLUMN : TABLE_NAME VARCHAR(128),              -- Table name
COLUMN : TYPE VARCHAR(4),                      -- FCO | SCO
COLUMN : OWNER VARCHAR(2),                     -- 1 | 0
COLUMN : VERSION VARCHAR(20),                  -- JPOX version
COLUMN : INTERFACE_NAME VARCHAR(255)           -- Fully qualified persistent Class type 
                                               -- of the persistent Interface implemented
)

With this autostarter mechanism from JPOX RDBMS 1.2.2 you can also set the persistence property org.jpox.rdbms.schemaTable.tableName to have the table called what you want (the default is JPOX_TABLES).

In some situations you may need to overwrite the default database schema used by the SchemaTable. There is an experimental version of "SchemaTable" known as "SchemaTable2". If you set your "org.jpox.autoStartMechanism" to this then you have the option of overriding the table definition for JPOX_TABLES. To configure the SchemaTable2, simply add a package.jdo file to the root of the Classpath that loads the JPOX RDBMS jar. Use the following sample and change as needed.


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jdo PUBLIC
    "-//Sun Microsystems, Inc.//DTD Java Data Objects Metadata 2.0//EN"
    "http://java.sun.com/dtd/jdo_2_0.dtd">
<jdo>
    <package name="org.jpox.store.rdbms">
        <class name="SchemaTable2" table="JPOX_TABLES">
            <field name="className" primary-key="true">
                <column name="CLASS_NAME" length="128" jdbc-type="VARCHAR"/>
            </field>
            <field name="tableName">
                <column name="TABLE_NAME" length="128" jdbc-type="VARCHAR"/>
            </field>
            <field name="type">
                <column name="TYPE" length="4" jdbc-type="VARCHAR"/>
            </field>
            <field name="owner">
                <column name="OWNER" length="2" jdbc-type="VARCHAR"/>
            </field>
            <field name="version">
                <column name="VERSION" length="20" jdbc-type="VARCHAR"/>
            </field>
            <field name="interfaceName">
                <column name="INTERFACE_NAME" length="255" jdbc-type="VARCHAR"/>
            </field>
        </class>
    </package>
</jdo>