Persistence Manager Factory

Any JDO-enabled application will require at least one PersistenceManagerFactory . Typically applications create one per datastore being utilised. A PersistenceManagerFactory provides access to PersistenceManager s 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.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.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);

Another alternative would be to call JDOHelper.getPersistenceManagerFactory(jndiLocation, context); , hence accessing the properties via JNDI.

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.



JDO Persistence Properties
Name Description
javax.jdo.PersistenceManagerFactoryClass The name of the PersistenceManager implementation. org.datanucleus.jdo.JDOPersistenceManagerFactory
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.ConnectionDriverURL Alias for datanucleus.ConnectionDriverURL
javax.jdo.option.ConnectionUserName Alias for datanucleus.ConnectionUserName
javax.jdo.option.ConnectionPassword Alias for datanucleus.ConnectionPassword
javax.jdo.option.IgnoreCache Alias for datanucleus.IgnoreCache
javax.jdo.option.Multithreaded Alias for datanucleus.Multithreaded
javax.jdo.option.NontransactionalRead Alias for datanucleus.NontransactionalRead
javax.jdo.option.NontransactionalWrite Alias for datanucleus.NontransactionalWrite
javax.jdo.option.Optimistic Alias for datanucleus.Optimistic
javax.jdo.option.RetainValues Alias for datanucleus.RetainValues
javax.jdo.option.RestoreValues 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 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 Alias for datanucleus.CopyOnAttach This is new in JDO2.1
javax.jdo.option.ReadOnly Alias for datanucleus.readOnlyDatastore This is new in JDO2.2


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

Named PMFs

Typically applications create one PMF per datastore being utilised. JDO2.1 provides a way of creating a PMF with a particular name and set of properties. This utilises a configuration file that defines the named PMFs. This configuration file is called jdoconfig.xml , and is located under "META-INF/". Let's see an example of a jdoconfig.xml 

<?xml version="1.0" encoding="utf-8"?>
<jdoconfig xmlns="http://java.sun.com/xml/ns/jdo/jdoconfig"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://java.sun.com/xml/ns/jdo/jdoconfig">

    <!-- Datastore Txn PMF -->
    <persistence-manager-factory name="Datastore">
        <property name="javax.jdo.PersistenceManagerFactoryClass"
            value="org.datanucleus.jdo.JDOPersistenceManagerFactory"/>
        <property name="javax.jdo.option.ConnectionDriverName"
            value="com.mysql.jdbc.Driver"/>
        <property name="javax.jdo.option.ConnectionURL"
            value="jdbc:mysql://localhost/datanucleus?useServerPrepStmts=false"/>
        <property name="javax.jdo.option.ConnectionUserName"
            value="datanucleus"/>
        <property name="javax.jdo.option.ConnectionPassword"
            value=""/>
        <property name="javax.jdo.option.Optimistic"
            value="false"/>
        <property name="datanucleus.autoCreateSchema"
            value="true"/>
    </persistence-manager-factory>

    <!-- Optimistic Txn PMF -->
    <persistence-manager-factory name="Optimistic">
        <property name="javax.jdo.PersistenceManagerFactoryClass"
            value="org.datanucleus.jdo.JDOPersistenceManagerFactory"/>
        <property name="javax.jdo.option.ConnectionDriverName"
            value="com.mysql.jdbc.Driver"/>
        <property name="javax.jdo.option.ConnectionURL"
            value="jdbc:mysql://localhost/datanucleus?useServerPrepStmts=false"/>
        <property name="javax.jdo.option.ConnectionUserName"
            value="datanucleus"/>
        <property name="javax.jdo.option.ConnectionPassword"
            value=""/>
        <property name="javax.jdo.option.Optimistic"
            value="true"/>
        <property name="datanucleus.autoCreateSchema"
            value="true"/>
    </persistence-manager-factory>

</jdoconfig>

So in this example we have 2 named PMFs. The first is known by the name "Datastore" and utilises datastore transactions. The second is known by the name "Optimistic" and utilises optimistic transactions. You simply define all properties for the particular PMF within its specification block. And finally we instantiate our PMF like this 

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

That's it. The PMF we are returned from JDOHelper will have all of the properties defined in jdoconfig.xml under the name of "Optimistic".