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 PersistenceManagerFactory 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.
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.
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 PMF 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.
With SchemaTable, JPOX 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.
With Classes, the user provides to the PMF the list of classes to use as the initial list
of classes to be persisted. They specify this via the PMF 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. This is available from version 1.1.0-beta-3
