Class JOP.persist.PersistManager
All Packages  Class Hierarchy  This Package  Previous  Next  Index  Home

Class JOP.persist.PersistManager

java.lang.Object
   |
   +----JOP.persist.PersistManager

public class PersistManager
extends Object
The PersistManager is the class that provides JOP's basic functionality. Specialisations of this class exist for each type of database (eg JDBC or RandomAccessFile).

To save an object a developer needs to do two things. First open a persist manager somewhere in the mainline of your program:

    String  driver = "jdbc.odbc.JdbcOdbcDriver" ;
    String  url = "jdbc:odbc:mydatabase" ;
    PersistManager pmgr = new JdbcPersistManager( driver,
                                                  url,
                                                  "user",
                                                  "password") ;
    pmgr.open() ;

and then use the persist manager to save your object. This will also automatically save all the objects that are referenced by your object.

    YourClass myObject = ... ;
    long objectId = pmgr.streamOutObject( myObject ) ;

The objectId is a unique identifier for your object returned by JOP. To retrieve the saved object (and all of its references) in another program or in a later session simply pass the objectId as follows:

    aNewObject = (YourClass)pmgr.streamInObject( objectId )

In the above example aNewObject will have identical content to myObject, including all the references of myObject.

JOP also supports the saving and retrieval of named objects.

JOP's internal cache ensures that aNewObject and myObject will be references to the exact same object if the above operations are performed within a unit of work


Method Index

 o abortWork()
Aborts a unit of work and resets any information used to maintain consistency.
 o beginWork()
Start a unit of work.
 o close()
The close() method is used to signal the end of use of the PersistManager.
 o commitWork()
Ends a unit of work.
 o idWork()
Each consistency unit is assigned an identifier (within the current process).
 o open()
The open() method is used to commence persistent operations.
 o streamInObject(long)
Retrieves an object previously saved by 'streamOutObject()'.
 o streamInRoot(String)
Retrieves an object previously saved by 'streamOutRoot()'.
 o streamOutObject(Object)
Save the object to the persistent database.
 o streamOutRoot(String, Object)
Save a named object to the persistent database.

Methods

 o streamOutObject
  public abstract long streamOutObject(Object o) throws Exception
Save the object to the persistent database. The object should either implement Persistable or have a custom marshall class or it will be marshalled automatically using native methods. The object and all of the objects referenced by the object are saved. Loops are detected and avoided.

To retrieve the object call 'streamInObject()'

Parameters:
o - The object to be saved
Returns:
s The unique identifier of the object
See Also:
Persistable, PersistMarshall
 o streamInObject
  public abstract Object streamInObject(long oid) throws Exception
Retrieves an object previously saved by 'streamOutObject()'. The unique object id is passed and an object and all of the objects referenced by the object are returned. The object will be an instance of the same type that was saved and will have the same context. The caller of this method must explicitly cast the returned object before using it.

Within a unit of work multiple reads of an object either directly (via this method) or indirectly because the object is referenced by another object will not create secondary instances.

Parameters:
id - Unique indentifier of the object
Returns:
s The object or throws ObjectNotFoundException
 o streamOutRoot
  public void streamOutRoot(String name,
                            Object o) throws Exception
Save a named object to the persistent database. Named objects are useful for well-defined objects to start an application (typically a hashtable or vector). The object should either implement Persistable or have a custom marshall class or it will be marshalled automatically using native methods. The object and all of the objects referenced by the object are saved. Loops are detected and avoided.

To retrieve the object call 'streamInRoot()' using the same name as was used to save the object.

Parameters:
o - The object to be saved
See Also:
Persistable, PersistMarshall
 o streamInRoot
  public Object streamInRoot(String name) throws Exception
Retrieves an object previously saved by 'streamOutRoot()'. The name used to save the object is used to retrieve the object. The object and all of the objects referenced by the object are returned. The object will be an instance of the same type that was saved and will have the same context. The caller of this method must explicitly cast the returned object before using it.

Parameters:
id - Unique indentifier of the object
Returns:
s The object or throws ObjectNotFoundException
 o beginWork
  public final void beginWork() throws Exception
Start a unit of work. If the same unique object id is referenced multiple times within a unit of work then the exact same object instance will be returned each time. Once outside of the unit of work a different instance may be returned (therefore there may be more than one object instance in the application that has the same 'id'). Objects saved within a unit of work and then read within the same unit of work will return the 'dirty' value of the object.

When a transactional resource manager (eg a relational database) implements this method, it corresponds to the start of a transaction. The exact semantics of the unit of work are therefore defined for each implementation of the PersistManager.

Consistency units can be nested.

 o commitWork
  public final void commitWork() throws Exception
Ends a unit of work. If the resource manager supports transactions then the transaction is committed (when the nesting level is zero).

 o abortWork
  public final void abortWork() throws Exception
Aborts a unit of work and resets any information used to maintain consistency.
 o idWork
  public int idWork() throws Exception
Each consistency unit is assigned an identifier (within the current process). This identifier can be useful to allow external objects to synchronize their cache with the PersistManager.

Returns:
s Consistency unit identifier
 o open
  public abstract void open() throws Exception
The open() method is used to commence persistent operations. It should be called before any other method is called.
 o close
  public abstract void close() throws Exception
The close() method is used to signal the end of use of the PersistManager. Once closed a PersistManager cannot be used again.

All Packages  Class Hierarchy  This Package  Previous  Next  Index  Home