C.1 Interfaces

An application uses the following Java interfaces and JDOHelper class in a JDO environment.

An Extent is used to access all of the instances of a particular class and, optionally, its subclasses. An application can either iterate over all the instances or use the extent as the set of candidates instances filtered with a Query.

public interface Extent {
    public void                 close(Iterator it);
    public void                 closeAll(  );
    public Class                getCandidateClass(  );
    public PersistenceManager   getPersistenceManager(  );
    public boolean              hasSubclasses(  );
    public Iterator             iterator(  );
}

Returned by

PersistenceManager.getExtent( )

Passed to

PersistenceManager.newQuery( ), Query.setCandidates( )

A persistent class can implement the InstanceCallbacks interface so that the following callback methods are called when particular lifecycle events occur:

public interface InstanceCallbacks {
    public void                 jdoPostLoad(  );
    public void                 jdoPreClear(  );
    public void                 jdoPreDelete(  );
    public void                 jdoPreStore(  );
}

This helper class provides applications with several utility methods. It provides methods to perform the following functions:

• Construct a PersistenceManagerFactory instance via a Properties object

• Interrogate the lifecycle state of an instance

• Get the object identifier of an instance

• Mark a field of an instance as modified

public class JDOHelper { 
    public                      JDOHelper(  );
    public static Object        getObjectId(Object obj); 
    public static PersistenceManager
                                getPersistenceManager(Object obj);
    public static PersistenceManagerFactory
                                getPersistenceManagerFactory(Properties props);
    public static PersistenceManagerFactory
                                getPersistenceManagerFactory(Properties props,
                                           ClassLoader cl);
    public static Object        getTransactionalObjectId(Object obj);
    public static boolean       isDeleted(Object obj);
    public static boolean       isDirty(Object obj);
    public static boolean       isNew(Object obj);
    public static boolean       isPersistent(Object obj);
    public static boolean       isTransactional(Object obj);
    public static void          makeDirty(Object obj, String fieldName);
}

The PersistenceManager interface is the primary interface for JDO-aware software. It is the factory for Query and Transaction instances, and it contains methods to manage the lifecycle of instances.

public interface PersistenceManager {
    public void                close(  );
    public Transaction         currentTransaction(  );
    public void                deletePersistent(Object obj);
    public void                deletePersistentAll(Object[] objs);
    public void                deletePersistentAll(Collection objs);
    public void                evict(Object obj);
    public void                evictAll(Object[] objs);
    public void                evictAll(Collection objs);
    public void                evictAll(  );
    public Extent              getExtent(Class persistenceCapableClass,
                                          boolean subclasses);
    public boolean             getIgnoreCache(  );
    public boolean             getMultithreaded(  );
    public Object              getObjectById(Object oid, boolean validate);
    public Object              getObjectId(Object obj);
    public Class               getObjectIdClass(Class cls);
    public PersistenceManagerFactory
                               getPersistenceManagerFactory(  );
    public Object              getTransactionalObjectId(Object obj);
    public Object              getUserObject(  );
    public boolean             isClosed(  );
    public void                makeNontransactional(Object obj);
    public void                makeNontransactionalAll(Object[] objs);
    public void                makeNontransactionalAll(Collection objs);
    public void                makePersistent(Object obj);
    public void                makePersistentAll(Object[] objs);
    public void                makePersistentAll(Collection objs);
    public void                makeTransactional(Object obj);
    public void                makeTransactionalAll(Object[] objs);
    public void                makeTransactionalAll(Collection objs);
    public void                makeTransient(Object obj);
    public void                makeTransientAll(Object[] objs);
    public void                makeTransientAll(Collection objs);
    public Object              newObjectIdInstance(Class pcClass, String str);
    public Query               newQuery(  );
    public Query               newQuery(Object compiled);
    public Query               newQuery(String language, Object query);
    public Query               newQuery(Class cls);
    public Query               newQuery(Extent cln);
    public Query               newQuery(Class cls, Collection cln);
    public Query               newQuery(Class cls, String filter);
    public Query               newQuery(Class cls, Collection cln, String filter);
    public Query               newQuery(Extent cln, String filter);
    public void                refresh(Object obj);
    public void                refreshAll(Object[] objs);
    public void                refreshAll(Collection objs);
    public void                refreshAll(  );
    public void                retrieve(Object obj);
    public void                retrieveAll(Collection objs);
    public void                retrieveAll(Collection objs, boolean DFGonly);
    public void                retrieveAll(Object[] objs);
    public void                retrieveAll(Object[] objs, boolean DFGonly);
    public void                setIgnoreCache(boolean flag);
    public void                setMultithreaded(boolean flag);
    public void                setUserObject(Object o);
}

Returned by:

PersistenceManagerFactory.getPersistenceManager( ),Extent.getPersistenceManager( ), Query.getPersistenceManager( ),Transaction.getPersistenceManager( ),JDOHelper.getPersistenceManager( )

The PersistenceManagerFactory is used to obtain PersistenceManager instances. All PersistenceManager instances obtained from the same PersistenceManagerFactory will have the same default properties.

PersistenceManagerFactory instances may be configured and serialized for later use. They may be stored via JNDI and looked up and used later. Any configured properties will be saved and restored.

If the ConnectionFactory property is set (non-null) then all the other connection properties (including ConnectionFactoryName) are ignored; otherwise, if ConnectionFactoryName is set (non-null) then all other connection properties are ignored. Similarly, if the ConnectionFactory2 property is set (non-null), then ConnectionFactory2Name is ignored.

public interface PersistenceManagerFactory implements Serializable {
    public void                close(  );
    public String              getConnectionDriverName(  );
    public Object              getConnectionFactory(  );
    public Object              getConnectionFactory2(  );
    public String              getConnectionFactory2Name(  );
    public String              getConnectionFactoryName(  );
    public String              getConnectionURL(  );
    public String              getConnectionUserName(  );
    public boolean             getIgnoreCache(  );
    public boolean             getMultithreaded(  );
    public boolean             getNontransactionalRead(  );
    public boolean             getNontransactionalWrite(  );
    public boolean             getOptimistic(  );
    public PersistenceManager  getPersistenceManager(  );
    public PersistenceManager  getPersistenceManager(String userid, String password);
    public Properties          getProperties(  );
    public boolean             getRestoreValues(  );
    public boolean             getRetainValues(  );
    public void                setConnectionDriverName(String driverName);
    public void                setConnectionFactory(Object connectionFactory);
    public void                setConnectionFactory2(Object connectionFactory);
    public void                setConnectionFactory2Name(
                                     String connectionFactoryName);
    public void                setConnectionFactoryName(
                                     String connectionFactoryName);
    public void                setConnectionPassword(String password);
    public void                setConnectionURL(String URL);
    public void                setConnectionUserName(String userName);
    public void                setIgnoreCache(boolean flag);
    public void                setMultithreaded(boolean flag);
    public void                setNontransactionalRead(boolean flag);
    public void                setNontransactionalWrite(boolean flag);
    public void                setOptimistic(boolean flag);
    public void                setRestoreValues(boolean restoreValues);
    public void                setRetainValues(boolean flag);
    public Collection          supportedOptions(  );
}

Returned by

JDOHelper.getPersistenceManagerFactory( ),PersistenceManager.getPersistenceManagerFactory( )

The Query interface allows applications to obtain persistent instances from the datastore. The PersistenceManager is the factory for Query instances. There may be many Query instances associated with a PersistenceManager.

public interface Query implements Serializable {
    public void                closeAll(  );
    public void                compile(  );
    public void                declareImports(String imports);
    public void                declareParameters(String parameters);
    public void                declareVariables(String variables);
    public Object              execute(  );
    public Object              execute(Object p1);
    public Object              execute(Object p1, Object p2);
    public Object              execute(Object p1, Object p2, Object p3);
    public Object              executeWithArray(Object[] parameters);
    public Object              executeWithMap(Map parameters);
    public boolean             getIgnoreCache(  );
    public PersistenceManager  getPersistenceManager(  );
    public void                setCandidates(Extent objs);
    public void                setCandidates(Collection objs);
    public void                setClass(Class cls);
    public void                setFilter(String filter);
    public void                setIgnoreCache(boolean ignoreCache);
    public void                setOrdering(String ordering);
}

Returned by

PersistenceManager.newQuery( )

The Transaction interface provides for initiation and completion of transactions under user control. It also provides methods for setting various options that control transaction behavior during a transaction and cache behavior after the transaction completes.

public interface Transaction {
    public void                begin(  );
    public void                commit(  );
    public boolean             getNontransactionalRead(  );
    public boolean             getNontransactionalWrite(  );
    public boolean             getOptimistic(  );
    public PersistenceManager  getPersistenceManager(  );
    public boolean             getRestoreValues(  );
    public boolean             getRetainValues(  );
    public Synchronization     getSynchronization(  );
    public boolean             isActive(  );
    public void                rollback(  );
    public void                setNontransactionalRead(
                                    boolean nontransactionalRead);
    public void                setNontransactionalWrite(
                                    boolean nontransactionalWrite);
    public void                setOptimistic(boolean optimistic);
    public void                setRestoreValues(boolean restoreValues);
    public void                setRetainValues(boolean retainValues);
    public void                setSynchronization(Synchronization sync);
}

Returned by

PersistenceManager.currentTransaction( )