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