7.5 Multithreading

You may have a simple application that requires only a single transaction at a time. It would use a single PersistenceManager and may perform successive transactions using the associated Transaction instance. You may have only a single thread accessing the persistent instances and instances of the JDO interface, but you may want multiple threads to access instances. In this case, you need to inform the JDO implementation that multiple threads are accessing the JDO environment.

A JDO implementation is thread safe, which means that its behavior is predictable in the presence of multiple application threads. When the application accesses and modifies persistent or transactional fields of persistent instances, the PersistenceManager performs its operations as if the operations were serialized. It is free to serialize internal data structures and order multithreaded operations in any way it chooses. The only application-visible behavior is that operations might block indefinitely (but not infinitely) while other operations complete.

Synchronizing a PersistenceManager instance is a relatively expensive operation. Many applications do not need multiple threads using the same PersistenceManager instance. If your application has multiple threads accessing a PersistenceManager or the instances it manages (e.g., persistent or transactional instances of persistent classes, instances of Transaction or Query, query results, etc.), you need to notify the PersistenceManager that multiple threads may access it.

You notify a PersistenceManager that it may be used by multiple application threads by setting the Multithreaded flag to true. This instructs the PersistenceManager to synchronize internally to avoid corruption of data structures due to multiple application threads. You call the following methods to get and set the Multithreaded flag:

boolean getMultithreaded(  );
void    setMultithreaded(boolean flag);

These methods are available in the PersistenceManagerFactory and PersistenceManager interfaces. You can also set the flag via the javax.jdo.option.Multithreaded property when you construct the PersistenceManagerFactory. You can also perform your own synchronization. In this case, you would set the Multithreaded flag to false.

JDO implementations do not use user-visible instances (e.g., instances of PersistenceManagerFactory, PersistenceManager, Transaction, Query, etc.) as synchronization objects, with one exception. The implementation must synchronize instances of persistent classes during a state transition that replaces the StateManager. This occurs if the application attempts to make the same instance persistent concurrently in multiple PersistenceManager instances.

If your application needs to serialize its own operations, you must implement your own appropriate synchronizing behavior, using instances visible to the application. This may include JDO interface instances (e.g., PersistenceManager, Query, etc.) and instances of your persistent classes.