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
Table of Contents
JDO recognizes many standard runtime properties, all of which Kodo JDO supports (these properties are also covered in the JDO Overview).
Property name: javax.jdo.PersistenceManagerFactoryClass
Configuration API: com.solarmetric.kodo.conf.Configuration.getPersistenceManagerFactoryClass
Resource adaptor config-property: 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.
Property name: javax.jdo.option.Optimistic
Configuration API: com.solarmetric.kodo.conf.Configuration.getOptimistic
Resource adaptor config-property: Optimistic
Default: true
Description: Selects between optimistic and pessimistic (data store) transactional modes.
Property name: javax.jdo.option.Multithreaded
Configuration API: com.solarmetric.kodo.conf.Configuration.getMultithreaded
Resource adaptor config-property: 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.
Property name: javax.jdo.option.IgnoreCache
Configuration API: com.solarmetric.kodo.conf.Configuration.getIgnoreCache
Resource adaptor config-property: 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.
Property name: javax.jdo.option.RetainValues
Configuration API: com.solarmetric.kodo.conf.Configuration.getRetainValues
Resource adaptor config-property: 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.
Property name: javax.jdo.option.RestoreValues
Configuration API: com.solarmetric.kodo.conf.Configuration.getRestoreValues
Resource adaptor config-property: 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.
Property name: javax.jdo.option.NontransactionalRead
Configuration API: com.solarmetric.kodo.conf.Configuration.getNontransactionalRead
Resource adaptor config-property: 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.
Property name: javax.jdo.option.NontransactionalWrite
Configuration API: com.solarmetric.kodo.conf.Configuration.getNontransactionalWrite
Resource adaptor config-property: 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.
Property name: javax.jdo.option.ConnectionURL
Configuration API: com.solarmetric.kodo.conf.Configuration.getConnectionURL
Resource adaptor config-property: ConnectionURL
Default: none
Description: The URL for the data source.
Property name: javax.jdo.option.ConnectionUserName
Configuration API: com.solarmetric.kodo.conf.Configuration.getConnectionUserName
Resource adaptor config-property: ConnectionUserName
Default: none
Description: The username for the connection listed in ConnectionURL.
Property name: javax.jdo.option.ConnectionPassword
Configuration API: com.solarmetric.kodo.conf.Configuration.getConnectionPassword
Resource adaptor config-property: ConnectionPassword
Default: none
Description: The password for the user specified in ConnectionUserName
Property name: javax.jdo.option.ConnectionDriverName
Configuration API: com.solarmetric.kodo.conf.Configuration.getConnectionDriverName
Resource adaptor config-property: ConnectionDriverName
Default: none
Description: The class name of ether the JDBC java.sql.Driver, or an instance of a javax.sql.DataSource to use to connect to the data source.
Property name: javax.jdo.option.ConnectionFactoryName
Configuration API: com.solarmetric.kodo.conf.Configuration.getConnectionFactoryName
Resource adaptor config-property: ConnectionFactoryName
Default: none
Description: The JNDI name of the connection factory to use for obtaining connections.
Property name: javax.jdo.option.ConnectionFactory2Name
Configuration API: com.solarmetric.kodo.conf.Configuration.getConnectionFactory2Name
Resource adaptor config-property: ConnectionFactory2Name
Default: none
Description: The JNDI name of the connection factory to use for finding read-only connections.
Property name: javax.jdo.option.MinPool
Configuration API: com.solarmetric.kodo.conf.Configuration.getMinPool
Resource adaptor config-property: 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.
Property name: javax.jdo.option.MaxPool
Configuration API: com.solarmetric.kodo.conf.Configuration.getMaxPool
Resource adaptor config-property: 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.
Property name: javax.jdo.option.MsWait
Configuration API: com.solarmetric.kodo.conf.Configuration.getMsWait
Resource adaptor config-property: 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.