7.2. PersistenceManagerFactory Properties
Prev | Chapter 7. PersistenceManagerFactory | Next

## 7.2. PersistenceManagerFactory Properties

The majority of the `PersistenceManagerFactory` interface consists of Java bean-style "getter" and "setter" methods for several properties, represented by field declarations in the diagram at the beginning of this chapter. These properties can be grouped into two functional categories: datastore connection configuration and default `PersistenceManager` and `Transaction` options.

The sections below explain the meaning of each property. Many of these properties can be set through the `Properties` instance supplied to the aforementioned `getPersistenceManagerFactory` methods in `JDOHelper`. Where this is the case, the `Properties` key is displayed along with the method declarations.

### 7.2.1. Connection Configuration

Use the properties below to tell JDO implementations how to connect with your datastore.

    public String getConnectionUserName ();
    public void setConnectionUserName (String user);
    javax.jdo.option.ConnectionUserName

The user name to specify when connecting to the datastore.

    public String getConnectionPassword ();
    public void setConnectionPassword (String pass);
    javax.jdo.option.ConnectionPassword

The password to specify when connecting to the datastore.

    public String getConnectionURL ();
    public void setConnectionURL (String url);
    javax.jdo.option.ConnectionURL

The URL of the datastore.

    public String getConnectionDriverName ();
    public void setConnectionDriverName (String driver);
    javax.jdo.option.ConnectionDriverName

The full class name of the driver to use when interacting with the datastore.

    public String getConnectionFactoryName ();
    public void setConnectionFactoryName (String name);
    javax.jdo.option.ConnectionFactoryName

The JNDI location of a datastore connection factory. This property overrides the other datastore connection properties above.

    public Object getConnectionFactory ();
    public void setConnectionFactory (Object factory);

A datastore connection factory. This property overrides all other datastore connection properties above, including the `ConnectionFactoryName`. The exact type of the given factory is implementation-dependent. Many JDO implementations will expect a standard Java Connector Architecture (JCA) `ConnectionFactory`. Implementations layered on top of JDBC might expect a JDBC `DataSource`. Still other implementations might use other factory types.

| Note
Kodo uses JDBC `DataSource`s as connection factories.

    public String getConnectionFactory2Name ();
    public void setConnectionFactory2Name (String name);
    javax.jdo.option.ConnectionFactory2Name

In a managed environment, connections obtained from the primary connection factory may be automatically enlisted in any global transaction in progress. The JDO implementation might require an additional connection factory that is not configured to participate in global transactions. For example, Kodo's default algorithm for datastore identity generation requires its own non-managed transaction. Specify the JNDI location of this factory through this property.

    public Object getConnectionFactory2 ();
    public void setConnectionFactory2 (Object factory);

The connection factory used for local transactions. Overrides the `ConnectionFactory2Name` above.

### 7.2.2. PersistenceManager and Transaction Defaults

The settings below will become the default property values for the `PersistenceManager`s and associated `Transaction`s produced by the `PersistenceManagerFactory`. Some implementations may not fully support all properties. If you attempt to set a property to an unsupported value, the operation will throw a `JDOUnsupportedOptionException`.

    public boolean getMultithreaded ();
    public void setMultithreaded (boolean multithreaded);
    javax.jdo.option.Multithreaded

Set this property to `true` to indicate that `PersistenceManager`s or the persistence-capable objects they manage will be accessed concurrently by multiple threads in your application. Some JDO implementations might optimize performance by avoiding any synchronization when this property is left `false`.

    public boolean getOptimistic ();
    public void setOptimistic (boolean optimistic);
    javax.jdo.option.Optimistic

Set to `true` to use optimistic transactions by default. Section 9.1, “Transaction Types” discusses optimistic transactions.

    public boolean getRetainValues ();
    public void setRetainValues (boolean retain);
    javax.jdo.option.RetainValues

If this property is `true`, the fields of persistent objects will not be cleared on transaction commit. Otherwise, persistent fields are cleared on commit and re-read from the datastore the next time they are accessed.

    public boolean getRestoreValues ();
    public void setRestoreValues (boolean restore);
    javax.jdo.option.RestoreValues

Controls the behavior of persistent and transactional fields on transaction rollback. Set this property to `true` to restore the fields to the values they had when the transaction began.

    public boolean getNontransactionalRead ();
    public void setNontransactionalRead (boolean read);
    javax.jdo.option.NontransactionalRead

Specifies whether you can read persistent state outside of a transaction. If this property is `false`, any attempt to iterate an `Extent`, execute a `Query`, or access non-primary key persistent object fields outside of a transaction will result in a `JDOUserException`.

    public boolean getNontransactionalWrite ();
    public void setNontransactionalWrite (boolean write);
    javax.jdo.option.NontransactionalWrite

Specifies whether you can write to persistent objects and perform persistence operations outside of a transaction. If this property is `false`, any attempt to modify a persistent object outside of a transaction will result in a `JDOUserException`.

Note that changes made outside of a transaction are discarded if the modified object enters a datastore transaction, but retained if it enters an optimistic transaction. We cover transactions in Chapter 9, Transaction.

    public boolean getIgnoreCache ();
    public void setIgnoreCache (boolean ignore);
    javax.jdo.option.IgnoreCache

This property controls whether changes made to persistent instances in the current transaction are considered when evaluating queries. A value of `true` is a hint to the JDO runtime that changes in the current transaction can be ignored; this usually enables the implementation to run the query using the datastore's native query interface. A value of `false`, on the other hand, may force implementations to flush changes to the datastore before running queries, or to run transactional queries in memory, both of which can have a negative impact on performance.

    public boolean getDetachAllOnCommit ();
    public void setDetachAllOnCommit (boolean detach);
    javax.jdo.option.DetachAllOnCommit

`PersistenceManager`s can optionally detach their entire object cache when a transaction commits. This setting controls the default for `PersistenceManager`s produced by this factory. We discuss detachment in Section 8.7, “Detach and Attach Functionality”.

    public String getMapping ();
    public void setMapping (String mapping);
    javax.jdo.option.Mapping

The name of the logical mapping between your persistent classes and the datastore. Section 15.1, “Mapping Metadata Placement” describes how the mapping name is used to locate relational mapping metadata.

    public void addInstanceLifecycleListener (InstanceLifecycleListener listen,
        Class[] classesOfInterest);
    public void removeInstanceLifecycleListener (InstanceLifecycleListener listen);

Recall from Section 4.4.2, “InstanceLifecycleListener” that `InstanceLifecycleListener`s consume events fired by lifecycle changes in persistent objects. The methods above allow you to add and remove listeners that will be passed on to all `PersistenceManager`s the `PersistenceManagerFactory` creates in the future. See the same-named methods of the `PersistenceManager` interface in Section 8.2, “Configuration Properties” for API details.

| Note
Kodo supports all of the properties above. It recognizes many additional properties as well; see Chapter 2, Configuration of the Reference Guide for details.

Prev | Up | Next
Chapter 7. PersistenceManagerFactory | Home | 7.3. Obtaining PersistenceManagers