Chapter 2. Configuration Framework
Prev | Part III. Kodo JDO Reference Guide | Next

## Chapter 2. Configuration Framework

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, `PersistenceManagerFactory`s 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

## 2.1. JDO Standard Properties

JDO recognizes many standard runtime properties, all of which Kodo JDO supports (these properties are also covered in the JDO Overview).

### 2.1.1. javax.jdo.PersistenceManagerFactoryClass

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.

### 2.1.2. javax.jdo.option.Optimistic

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.

### 2.1.3. javax.jdo.option.Multithreaded

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.

### 2.1.4. javax.jdo.option.IgnoreCache

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.

### 2.1.5. javax.jdo.option.RetainValues

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.

### 2.1.6. javax.jdo.option.RestoreValues

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`.

### 2.1.7. javax.jdo.option.NontransactionalRead

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.

### 2.1.8. javax.jdo.option.NontransactionalWrite

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.

### 2.1.9. javax.jdo.option.ConnectionURL

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.

### 2.1.10. javax.jdo.option.ConnectionUserName

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`.

### 2.1.11. javax.jdo.option.ConnectionPassword

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`

### 2.1.12. javax.jdo.option.ConnectionDriverName

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.

### 2.1.13. javax.jdo.option.ConnectionFactoryName

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.

### 2.1.14. javax.jdo.option.ConnectionFactory2Name

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.

### 2.1.15. javax.jdo.option.MinPool

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.

### 2.1.16. javax.jdo.option.MaxPool

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.

### 2.1.17. javax.jdo.option.MsWait

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.

Prev | Up | Next
Chapter 1. Introduction | Home | 2.2. Kodo JDO Properties