JDO : PersistenceManagerFactory

Any JDO-enabled application will require at least one PersistenceManagerFactory (PMF). Typically applications create one per datastore being utilised. A PersistenceManagerFactory provides access to PersistenceManagers which allow objects to be persisted, and retrieved. The PersistenceManagerFactory can be configured to provide particular behaviour.

The simplest way of creating a PersistenceManagerFactory is as follows 

Properties properties = new Properties();
properties.setProperty("javax.jdo.PersistenceManagerFactoryClass",
                "org.datanucleus.api.jdo.JDOPersistenceManagerFactory");
properties.setProperty("javax.jdo.option.ConnectionDriverName","com.mysql.jdbc.Driver");
properties.setProperty("javax.jdo.option.ConnectionURL","jdbc:mysql://localhost/myDB");
properties.setProperty("javax.jdo.option.ConnectionUserName","login");
properties.setProperty("javax.jdo.option.ConnectionPassword","password");
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(properties);

A slight variation on this, is to use a file to specify these properties like this 

javax.jdo.PersistenceManagerFactoryClass=org.datanucleus.api.jdo.JDOPersistenceManagerFactory
javax.jdo.option.ConnectionDriverName=com.mysql.jdbc.Driver
javax.jdo.option.ConnectionURL=jdbc:mysql://localhost/myDB
javax.jdo.option.ConnectionUserName=login
javax.jdo.option.ConnectionPassword=password

and then to create the PersistenceManagerFactory using this file 

File propsFile = new File(filename);
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(propsFile);

or if the file is in the CLASSPATH (at "datanucleus.properties" in the root of the CLASSPATH), then 

PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory("datanucleus.properties");

or if using a META-INF/persistence.xml file, you can simply specify the persistence-unit name as 

PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory("myPersistenceUnit");

Another alternative, when specifying your datastore via JNDI, would be to call JDOHelper.getPersistenceManagerFactory(jndiLocation, context);, and then set the other persistence properties on the received PMF.

A PersistenceManagerFactory is designed to be thread-safe. A PersistenceManager is not

Whichever way we wish to obtain the PersistenceManagerFactory we have defined a series of properties to give the behaviour of the PersistenceManagerFactory. The first property specifies to use the DataNucleus implementation, and the following 4 properties define the datastore that it should connect to. There are many properties available. Some of these are standard JDO properties, and some are DataNucleus extensions.


Specifying the datastore properties

With JDO you have 3 ways of specifying the datastore via persistence properties

  • Specify the connection URL/driverName/userName/password and it will internally create a DataSource for this URL (with optional connection pooling). This is achieved by specifying javax.jdo.option.ConnectionDriverName, javax.jdo.option.ConnectionURL, javax.jdo.option.ConnectionUserName, and javax.jdo.option.ConnectionPassword
  • Specify the JNDI name of the connectionFactory This is achieved by specifying javax.jdo.option.ConnectionFactoryName, and javax.jdo.option.ConnectionFactory2Name (for secondary operations)
  • Specify the DataSource of the connectionFactory This is achieved by specifying javax.jdo.option.ConnectionFactory, and javax.jdo.option.ConnectionFactory2 (for secondary operations)

JDO Persistence Properties

Name Values Description
javax.jdo.PersistenceManagerFactoryClass The name of the PMF implementation. org.datanucleus.api.jdo.JDOPersistenceManagerFactory Only required if you have more than one JDO implementation in the CLASSPATH
javax.jdo.option.ConnectionFactory Alias for datanucleus.ConnectionFactory
javax.jdo.option.ConnectionFactory2 Alias for datanucleus.ConnectionFactory2
javax.jdo.option.ConnectionFactoryName Alias for datanucleus.ConnectionFactoryName
javax.jdo.option.ConnectionFactory2Name Alias for datanucleus.ConnectionFactory2Name
javax.jdo.option.ConnectionDriverName Alias for datanucleus.ConnectionDriverName
javax.jdo.option.ConnectionURL Alias for datanucleus.ConnectionURL
javax.jdo.option.ConnectionUserName Alias for datanucleus.ConnectionUserName
javax.jdo.option.ConnectionPassword Alias for datanucleus.ConnectionPassword
javax.jdo.option.IgnoreCache true | false Alias for datanucleus.IgnoreCache
javax.jdo.option.Multithreaded true | false Alias for datanucleus.Multithreaded
javax.jdo.option.NontransactionalRead false | true Alias for datanucleus.NontransactionalRead
javax.jdo.option.NontransactionalWrite false | true Alias for datanucleus.NontransactionalWrite
javax.jdo.option.Optimistic true | false Alias for datanucleus.Optimistic
javax.jdo.option.RetainValues true | false Alias for datanucleus.RetainValues
javax.jdo.option.RestoreValues true | false Alias for datanucleus.RestoreValues
javax.jdo.option.Mapping Alias for datanucleus.Mapping RDBMS datastores only
javax.jdo.mapping.Catalog Alias for datanucleus.Catalog RDBMS datastores only
javax.jdo.mapping.Schema Alias for datanucleus.Schema RDBMS datastores only
javax.jdo.option.DetachAllOnCommit true | false Alias for datanucleus.DetachAllOnCommit
javax.jdo.option.TransactionType Alias for datanucleus.TransactionType This is new in JDO2.1
javax.jdo.option.PersistenceUnitName Alias for datanucleus.PersistenceUnitName This is new in JDO2.1
javax.jdo.option.ServerTimeZoneID Alias for datanucleus.ServerTimeZoneID This is new in JDO2.1
javax.jdo.option.Name Name of the PMF to use. This is for use with "named PMF" functionality in JDO 2.1 referring to a PMF defined in "jdoconfig.xml".
javax.jdo.option.CopyOnAttach true | false Alias for datanucleus.CopyOnAttach This is new in JDO2.1
javax.jdo.option.ReadOnly true | false Alias for datanucleus.readOnlyDatastore This is new in JDO2.2
javax.jdo.option.TransactionIsolationLevel Alias for datanucleus.transactionIsolation This is new in JDO2.2
javax.jdo.option.DatastoreReadTimeoutMillis Alias for datanucleus.datastoreReadTimeout This is new in JDO2.3
javax.jdo.option.DatastoreWriteTimeoutMillis Alias for datanucleus.datastoreWriteTimeout This is new in JDO2.3

DataNucleus provides many properties to extend the control that JDO gives you. These can be used alongside the above standard JDO properties, but will only work with DataNucleus. Please consult the Persistence Properties Guide for full details.