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: data store 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 passed to the aforementioned getPersistenceManagerFactory method in JDOHelper. Where this is the case, the the properties configuration code is displayed along with the method declarations.
Use the properties below to tell JDO implementations how to connect with your data store.
public String getConnectionUserName (); public void setConnectionUserName (String user); props.setProperty ("javax.jdo.option.ConnectionUserName", user);
The user name to specify when connecting to the data store.
public String getConnectionPassword (); public void setConnectionPassword (String pass); props.setProperty ("javax.jdo.option.ConnectionPassword", pass);
The password to specify when connecting to the data store.
public String getConnectionURL (); public void setConnectionURL (String url); props.setProperty ("javax.jdo.option.ConnectionURL", url);
The URL of the data store.
public String getConnectionDriverName (); public void setConnectionDriverName (String driver); props.setProperty ("javax.jdo.option.ConnectionDriverName", driver);
The full class name of the driver to use when interacting with the data store.
public String getConnectionFactoryName (); public void setConnectionFactoryName (String name); props.setProperty ("javax.jdo.option.ConnectionFactoryName", name);
The JNDI location of a connection factory to use to obtain data store connections. This property overrides the other data store connection properties above.
public Object getConnectionFactory (); public void setConnectionFactory (Object factory);
A connection factory to use to obtain data store connections. This property overrides all other data store 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.
Kodo JDO uses JDBC DataSources as connection factories.
public String getConnectionFactory2Name (); public void setConnectionFactory2Name (String name); props.setProperty ("javax.jdo.option.ConnectionFactory2Name", name);
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. The JNDI location of this factory can be specified through this property.
public Object getConnectionFactory2 (); public void setConnectionFactory2 (Object factory);
The connection factory to use for local transactions. Overrides the ConnectionFactory2Name above.
The settings below will become the default property values for the PersistenceManagers and associated Transactions 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); props.setProperty ("javax.jdo.option.Multithreaded", multithreaded);
Set this property to true to indicate that PersistenceManagers 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); props.setProperty ("javax.jdo.option.Optimistic", optimistic);
Set to true to use optimistic transactions by default. The section on transaction types discusses optimistic transactions.
public boolean getRetainValues (); public void setRetainValues (boolean retain); props.setProperty ("javax.jdo.option.RetainValues", retain);
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 data store the next time they are accessed.
public boolean getRestoreValues (); public void setRestoreValues (boolean restore); props.setProperty ("javax.jdo.option.RestoreValues", restore);
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); props.setProperty ("javax.jdo.option.NontransactionalRead", read);
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); props.setProperty ("javax.jdo.option.NontransactionalWrite", write);
Specifies whether you can write to persistent fields outside of a transaction. If this property is false, any attempt to modify a persistent field outside of a transaction will result in a JDOUserException.
Note that changes made outside of a transaction are never flushed to the data store. The changes are discarded as soon as the modified object enters a transaction.
public boolean getIgnoreCache (); public void setIgnoreCache (boolean ignore); props.setProperty ("javax.jdo.option.IgnoreCache", ignore);
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 data store's native query interface. A value of false, on the other hand, may force implementations to flush changes to the data store before running queries, or to run transactional queries in memory, both of which can have a negative impact on performance.
Kodo JDO supports all PersistenceManager and Transaction properties. It recognizes many additional properties as well; see the Kodo JDO Reference Guide for details.