org.garret.consus
Interface PersistentObjectStorage

All Known Subinterfaces:

ConsusConnection

All Known Implementing Classes:

JDBCObjectRelationalAdapter

public interface PersistentObjectStorage

The interface of persistent object storage. This interface declares methods for the object oriented Consus API. This interface is implemented by ConsusConnection and JDBCObjectRelationalAdapter. These methods can be used either with the native Consus database engine or with any other DBMS with a JDBC interface through the object-relational adapter.

Method Summary

void	becomeObject(Persistent a, Persistent b) Exchange references to the obejcts in the database.
void	clearComponents(Persistent obj) Clear all object fields (to make it possible for GC to collect unused persistent object).
void	clearObjectCache() Throw all objects from the object cache.
void	deleteObject(Persistent obj) Remove object from the database.
java.lang.Object	fetchObject(java.sql.ResultSet cursor) Fetch the current row of the cursor as a Java object.
java.lang.Object	getObjectByOid(long oid) Get object by object identifier.
int	getObjectCacheSize() Poll object cache size
TableIterator	getTableIterator(java.lang.String tableName) Get table iterator.
boolean	isInitialized() Returns true if the database has already been initialized.
void	loadComponents(Persistent obj) Load the components of the object.
void	loadObject(Persistent obj) Load the stub object or reload the object from the database.
void	lock() Lock database in exclusive mode.
void	open() Opens the persistent object storage.
void	storeObject(Persistent obj) Save object in the database.
void	updateObject(java.lang.Object obj, java.sql.ResultSet cursor) Update the current row of the cursor with the new values passed in the Java object.

Method Detail

becomeObject

void becomeObject(Persistent a,
                  Persistent b)
                  throws java.lang.Exception

Exchange references to the obejcts in the database. The result of execution A.become(B) is that OIDs of A and B are exchanged, so that all references to the A in the database will now refer to B, and visa versa. This operation doesn't affect references in the main memory. Object A should already have assigned OID (be stored in the database) If B is not yet stored in the database, it is explicitly assigned OID by this method.

Parameters:

a - object which OID will be exchanged with b object

b - object which OID will be exchanged with a object

Throws:

java.lang.Exception

clearComponents

void clearComponents(Persistent obj)
                     throws java.lang.Exception

Clear all object fields (to make it possible for GC to collect unused persistent object). If this method is not called and all pesistent object in the database are referencing each other (for example linked in L2-list), then after some time all data can be loaded to the memory from the database

Parameters:

obj - persitent object which components are cleared

Throws:

java.lang.Exception

clearObjectCache

void clearObjectCache()

Throw all objects from the object cache. This method should be called to prevent memory exhaustion caused by loading a lot of persistent interconnected objects (each of the objects is accessible from some set of root objects) from the database. GC will not be able to deallocate such objects because they are referencing each other. So finally all object from the database can be loaded to the memory. Programmer should check number of loaded objects (by getObjectCacheSize or getUsedMemorySize method) and if it axceeds some threshold, call clearObjectCache method to remove all objects from cache. Alternativly, progrtammer can call Persistent.unget method to replace object with a stub, but this approach is less efficient because usually it throws away most recently used object.

deleteObject

void deleteObject(Persistent obj)
                  throws java.lang.Exception

Remove object from the database.

Parameters:

obj - deleted persitent object

Throws:

java.lang.Exception

fetchObject

java.lang.Object fetchObject(java.sql.ResultSet cursor)
                             throws java.lang.Exception

Fetch the current row of the cursor as a Java object.

Parameters:

cursor - - result set with the current position corresponding to the fetched object

Returns:

fetched object

Throws:

java.lang.Exception

getObjectByOid

java.lang.Object getObjectByOid(long oid)
                                throws java.lang.Exception

Get object by object identifier.

Parameters:

oid - - identifier of object to be fetched

Returns:

object with specified OID

Throws:

java.lang.Exception

getObjectCacheSize

int getObjectCacheSize()

Poll object cache size

Returns:

number of object in object cache.

getTableIterator

TableIterator getTableIterator(java.lang.String tableName)
                               throws java.lang.Exception

Get table iterator. More efficient way for iteration through the the table then using "select * from" and ResultSet. Provide sequential access and direct access by key.

Parameters:

tableName - name of th table through which iteration will be performed

Returns:

table iterator for specified table

Throws:

java.lang.Exception

isInitialized

boolean isInitialized()
                      throws java.lang.Exception

Returns true if the database has already been initialized. If database was not initilialized, the programmer has to create TypeInfo, OidTable and applications tables, insert information about class-table mapping into TypeInfo table and initialize the ID counter by inserting a value in the OidTable. Initialization can be done through standard JDBC methods.

Returns:

true if database was already initialized, false otherwise

Throws:

java.lang.Exception

loadComponents

void loadComponents(Persistent obj)
                    throws java.lang.Exception

Load the components of the object. This method should be called for the classes that disable the implicit loading of object closure. In this case the referenced components should be loaded explicitly by this method.

Parameters:

obj - persistent object which components are loaded

Throws:

java.lang.Exception

loadObject

void loadObject(Persistent obj)
                throws java.lang.Exception

Load the stub object or reload the object from the database.

Parameters:

obj - loaded persistent object

Throws:

java.lang.Exception

lock

void lock()
          throws java.lang.Exception

Lock database in exclusive mode. The lock is kept until the end of transaction. This method should be called to prevent deadlocks caused by upgradin shared lock to exclusive. For example, if you first issue read-only statement and then, within the same transaction, update statement, it can be a reason of deadlock if concurrent thread also tries to upgrade shared lock to exclusive.

Throws:

java.lang.Exception

open

void open()
          throws java.lang.Exception

Opens the persistent object storage. This method should be called after checking that the storage has been initialized, and if not, then it needs to initialize it.

Throws:

java.lang.Exception

storeObject

void storeObject(Persistent obj)
                 throws java.lang.Exception

Save object in the database. If object referes to some some other persistent-capable objcts without assigned object identifiers, then these object will be also recursivley saved in the database.

Parameters:

obj - stored persitent object

Throws:

java.lang.Exception

updateObject

void updateObject(java.lang.Object obj,
                  java.sql.ResultSet cursor)
                  throws java.lang.Exception

Update the current row of the cursor with the new values passed in the Java object.

Parameters:

obj - - object with the new values

cursor - - result set with the current position pointing to the updated row

Throws:

java.lang.Exception