Table of Contents
Kodo JDO implements a unified configuration framework across its runtime environment and all of its development tools. The framework is based on SolarMetric's com.solarmetric.kodo.conf.Configuration interface. Concrete implementations of this interface and its subclasses are freely interchangeable with standard Java Properties objects, so most of your configuration will be through properties objects or properties files. For extreme customization, however, Kodo JDO's PersistenceManagerFactory implementation and its development tools allow you to manipulate the Configuration instance directly. See their Javadoc for details.
In JDO 1.0, PersistenceManagerFactorys are usually obtained through the JDOHelper.getPersistenceManagerFactory method, which takes a single Properties argument. The supplied properties are used to configure the JDO implementation. Similarly, all Kodo JDO development tools accept a -properties command-line flag specifying the location of a properties file to read from. This location can be given as either a path to a file, or as a resource name of a file somewhere in the CLASSPATH. Kodo JDO's tools use the same property keys as the runtime environment, so you can use the same properties files for both development and runtime.
The development tools and runtime environment also share a comprehensive system of property defaults and overrides defined by the Configuration interface:
All properties are defaulted to the values specified in an optional kodo.properties resource that can be placed in any top-level directory of the CLASSPATH.
You can customize the location of the above resource by specifying the correct resource name in the com.solarmetric.kodo.properties System property.
For users of the deprecated system.prefs configuration mechanism present in earlier versions of Kodo JDO, the information in your system.prefs will also be loaded as default values.
You can override any default value defined in the kodo.properties resource by setting the System property of the same name to the desired default value.
All Kodo JDO command-line tools accept flags to set the value of any property. The flag name is always the last token of the corresponding property name, capitalized as a Java identifier. For example, to set the JDO javax.jdo.option.ConnectionUserName property, you could pass the -connectionUserName <value> flag to any tool.
Kodo JDO also enables the creation and configuration of system plugins via properties. Plugin-related properties typically come in pairs: com.solarmetric.kodo.<property>Class and com.solarmetric.kodo.<property>Properties. The <property>Class key is used to specify the plugin's class, and the <property>Properties key is used to configure the plugin instance once it is instantiated. This configuration is automatic. Kodo JDO matches the keys supplied in the <property<Properties string to the setter methods of the plugin using Java bean naming conventions. The string must be of the form "<key1>=<value1> <key2>=<value2> ...". Consider the following example:
Suppose that you have created a new class, com.xyz.MyDataCache, that you wish to use in Kodo JDO's pluggable caching mechanism. MyDataCache has two configuration methods, setMaxSize (int) and setRemoteHost (String, int). You could plug your cache into Kodo JDO by specifying the following properties:
com.solarmetric.kodo.DataCacheClass: com.xyz.MyDataCache com.solarmetric.kodo.DataCacheProperties: maxSize=100 remoteHost=CacheServer,8080
JDO recognizes many standard runtime properties, all of which Kodo JDO supports (these properties are also covered in the JDO Overview):
javax.jdo.option.PersistenceManagerFactoryClass
Default: none
Description: The name of the concrete implementation of javax.jdo.PersistenceManagerFactory that javax.jdo.JDOHelper.getPersistenceManagerFactory () should create. For Kodo JDO, this should be com.solarmetric.kodo.impl.jdbc.JDBCPersistenceManagerFactory or com.solarmetric.kodo.impl.jdbc.ee.EEPersistenceManagerFactory, or a custom extension of one of these types.
javax.jdo.option.Optimistic
Default: true
Description: Selects between optimistic and pessimistic (data store) transactional modes.
javax.jdo.option.Multithreaded
Default: false
Description: If true, then the application plans to have multiple threads simultaneously accessing a single PersistenceManager, so measures must be taken to ensure that the implementation is thread-safe. Otherwise, the implementation need not address thread safety.
javax.jdo.option.IgnoreCache
Default: false
Description: If false, then the JDO implementation must consider modifications, deletions, and additions in the PersistenceManager transaction cache when executing a query inside a transaction. Else, the implementation is free to ignore the cache and execute the query directly against the data store.
javax.jdo.option.RetainValues
Default: true
Description: If true, then fields in a persistence-capable object that have been read during a transaction must be preserved in memory after the transaction commits. Otherwise, persistence-capable objects must transition to the hollow state upon commit, meaning that subsequent reads will result in a database round-trip.
javax.jdo.option.RestoreValues
Default: true
Description: If true, then fields in a persistence-capable object that have been changed during a transaction will be rolled back to their original values upon a rollback. Otherwise, the values will not be changed upon rollback.
javax.jdo.option.NontransactionalRead
Default: true
Description: If true, then it is possible to read persistent data outside the context of a transaction. Otherwise, a transaction must be in progress in order read data.
javax.jdo.option.NontransactionalWrite
Default: false
Description: If true, then it is possible to write to fields of a persistent-nontransactional object when a transaction is not in progress. If false, such a write will result in a JDOUserException.
javax.jdo.option.ConnectionURL
Default: none
Description: The URL for the data source.
javax.jdo.option.ConnectionUserName
Default: none
Description: The username for the connection listed in ConnectionURL.
javax.jdo.option.ConnectionPassword
Default: none
Description: The password for the user specified in ConnectionUserName
javax.jdo.option.ConnectionDriverName
Default: none
Description: The class name of the driver
javax.jdo.option.ConnectionFactoryName
Default: none
Description: The JNDI name of the connection factory to use for obtaining connections.
javax.jdo.option.ConnectionFactory2Name
Default: none
Description: The JNDI name of the connection factory to use for finding read-only connections.
javax.jdo.option.MinPool
Default: 0
Description: The minimum number of connections to keep in the pool. This option has been removed from the specification, but we still use the javax.jdo.option for backwards compatibility.
javax.jdo.option.MaxPool
Default: 10
Description: The maximum number of connections to pool. If all of these are in use, then PersistenceManager instances must wait for a connection to become available. This option has been removed from the specification, but we still use the javax.jdo.option for backwards compatibility.
javax.jdo.option.MsWait
Default: 0
Description: The number of milliseconds to wait for a pooled connection before throwing an exception if the pool is empty. This option has been removed from the specification, but we still use the javax.jdo.option for backwards compatibility.