3.4 Connecting to a Datastore

After a persistence-capable class has been defined, the next step is to implement an application that actually uses it. Any JDO application must get a connection to the underlying datastore before it can do anything. This is done by configuring an instance of PersistenceManagerFactory and then using it to get a PersistenceManager .

PersistenceManagerFactory is just a Java interface; JDO does not specify how an actual PersistenceManagerFactory instance should be created. However, it does provide a helper class called JDOHelper that, among other things, provides a common bootstrap mechanism to create a PersistenceManagerFactory instance based on a specified set of properties:

 static public PersistenceManagerFactory   getPersistenceManagerFactory(Properties props) 

The getPersistenceManagerFactory() method takes a set of properties as input and constructs a concrete instance of a PersistenceManagerFactory . The one required property is javax.jdo.PersistenceManagerFactoryClass , which is used to identify the name of an implementation's PersistenceManagerFactory class. All other properties are simply passed to the implementation's class and are implementation specific. These include things like connection URL, name, and password.

At a minimum, every JDO implementation must support bootstrapping via JDOHelper. Additionally, an implementation might provide its own PersistenceManagerFactory constructors that can be used to directly construct a PersistenceManagerFactory instance. It may also provide PersistentManager constructors to avoid having to go through a PersistenceManagerFactory at all. From a portability standpoint, these approaches are all JDO implementation specific.

PersistenceManagerFactory also implements Serializable . This allows a previously configured PersistenceManagerFactory instance to be located via JNDI.

After a PersistenceManagerFactory instance has been created, the getPersitenceManager() method can be used to get a PersistenceManager instance:

 public PersistenceManager getPersistenceManager() 

When an application is finished with a PersistenceManager instance, it should close it by calling the close() method:

 public void close() 

Connection Pooling

JDO leaves it up to the JDO implementation as to whether its PersistenceManagerFactory implements connection pooling. If implemented, the close() method on PersistenceManager may not physically close anything, but may instead return the PersistenceManager instance to the PersistenceManagerFactory to be reused.

The following code snippet taken from MakeConnectionExample.java shows how to get a PersistenceManager instance from a PersistenceManagerFactory and then close it:

 import java.util.Properties; import javax.jdo.*; public class MakeConnectionExample {   public static void main(String[] args) {     Properties properties = new Properties();     properties.put(       "javax.jdo.PersistenceManagerFactoryClass", "XXX");     properties.put(       "javax.jdo.option.ConnectionURL", "XXX");     properties.put(       "javax.jdo.option.ConnectionUserName", "XXX");     properties.put(       "javax.jdo.option.ConnectionPassword", "XXX");     PersistenceManagerFactory pmf =  JDOHelper.getPersistenceManagerFactory(properties);  PersistenceManager pm = pmf.getPersistenceManager();     /* Do something interesting */     pm.close();   } } 

Of course, before this example can be used, the "XXX" strings would need to be replaced with values appropriate to the JDO implementation being used.

As an alternative to hard coding the properties as in the previous example, it is generally better to specify them as system properties or read them from a file. The code for this chapter contains examples of how these two alternative approaches would work. See the following for more information:

• MakeConnectionFromSystemPropertiesExample.java

• MakeConnectionFromFileExample.java

For a full list of the standard JDO property names that can be specified, see Chapter 5.