com.xavax.xstore
Class PersistenceContext

Object
  PersistenceContext

public class PersistenceContext

extends Object

PersistenceContext provides the interface between a client thread and the persistence framework. A persistence context encapsulates an object directory and object cache which are isolated from the object directory and object cache of other persistence contexts. Persistent objects are created in the persistence context bound to the current thread. Methods are provided to find and delete persistent objects.

Transactions are supported by a persistence context and are isolated from the transactions of other contexts. A transaction begins when a persistence context is created or immediately after the more recent call to the commit or rollback method. The commit method traverses the object directory and persists all changes to the database within a single database transaction. The rollback method traverses the object directory casting out any modified or deleted objects and any objects that have not been persisted.

A persistence context can be bound to multiple threads while a thread can only be bound to one persistence context. The client determines whether threads share a persistence context by explicitly binding each thread to a new context or an existing context.

Method Summary

void	bind(Thread t) Bind this context to the specified thread.
void	close() Close this persistence context and return it to the context pool.
void	commit() Commit all changes to the database.
Criteria	createCriteria(String className) Create a search criteria object bound to the specified persistent class.
void	delete(AbstractProxy proxy) Delete the persistent object associated with a proxy.
void	delete(Collection c) Delete a collection of persistent objects.
void	delete(LOID loid) Delete the persistent object with the specified logical object ID.
Collection	find(Criteria sc) Find all objects that satisfy the search criteria.
Object	find(LOID loid) Find an object by LOID.
int	id() Returns the identifier for this context.
PersistenceManager	manager() Returns the persistence manager.
void	rollback() Rollback all changes to persistent objects.
void	setDefaultDatabase(String name) Set the default database.
void	showObjects() Display all objects in the object directory in a user-friendly format.
String	toString() Returns a string representation of this persistence context.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

bind

public void bind(Thread t)

Bind this context to the specified thread.

close

public void close()

Close this persistence context and return it to the context pool.

commit

public void commit()
            throws PersistenceException

Commit all changes to the database. Traverse the object directory, finding all objects that are either dirty, deleted, or not persisted and make the necessary changes. The result of this traversal is a set of prepared statement batches. Execute each batch, then commit the database transaction, release all connections, and reset the status flags of each object in the directory. If a runtime exception occurs, roll back all changes.

Throws:

PersistenceException

createCriteria

public Criteria createCriteria(String className)
                        throws ClassNotSupportedException,
                               PersistenceException

Create a search criteria object bound to the specified persistent class. The search criteria is then constructed using the methods of the Criteria class.

Parameters:

className - the name of the class of objects to be found using the search criteria.

Returns:

a search criteria object, or null if the specified class does not exist.

Throws:

ClassNotSupportedException

PersistenceException

delete

public void delete(LOID loid)
            throws ClassNotSupportedException,
                   InvalidReferenceException,
                   PersistenceException

Delete the persistent object with the specified logical object ID.

Parameters:

loid - the logical object ID of the object to be deleted.

Throws:

InvalidReferenceException - if the class ID or database ID is not valid.

ClassNotSupportedException - if the class specified in the LOID is not supported by the database specified in the LOID.

PersistenceException - if unable to create a proxy or instantiate an implementation object.

delete

public void delete(AbstractProxy proxy)

Delete the persistent object associated with a proxy.

Parameters:

proxy - a proxy for the object to be deleted.

delete

public void delete(Collection c)

Delete a collection of persistent objects.

Parameters:

c - a collection of proxies for persistent objects.

find

public Object find(LOID loid)
                      throws PersistenceException

Find an object by LOID. First search the object directory to see if the object is already loaded. If not, create a new proxy and an entry in the object directory.

Parameters:

loid - the logical object identifier.

Returns:

a proxy for the specified object.

Throws:

PersistenceException - if the object is not found.

find

public Collection find(Criteria sc)
                          throws PersistenceException

Find all objects that satisfy the search criteria.

Parameters:

sc - the search criteria.

Returns:

a Collection of the objects found.

Throws:

PersistenceException - if an SQL error occurred.

id

public int id()

Returns the identifier for this context.

Returns:

the identifier for this context.

manager

public PersistenceManager manager()

Returns the persistence manager.

Returns:

the persistence manager.

rollback

public void rollback()

Rollback all changes to persistent objects. Traverse the object directory removing the directory enty and implementation object for objects that are not yet persisted. For persisted objects, remove the implementation objects that are modified (which will force reloading) and reset the directory flags.

setDefaultDatabase

public void setDefaultDatabase(String name)
                        throws DatabaseNotRegisteredException

Set the default database. Objects created using operator new will be placed in this database. The specified name must match one of the databases configured in the database metadata.

Parameters:

name - the name of the new default database.

Throws:

DatabaseNotRegisteredException - if the specified database is not configured in the metadata.

showObjects

public void showObjects()

Display all objects in the object directory in a user-friendly format.

toString

public String toString()

Returns a string representation of this persistence context.

Returns:

a string representation of this persistence context.