org.garret.consus
Class Persistent

java.lang.Object
  org.garret.consus.Persistent

Direct Known Subclasses:

POCollection, POComparator, StringIndex

public class Persistent

extends java.lang.Object

Base class for all persistent-capable classes. You should derive your class from the Persistent class to support transparent persistency.

Field Summary

PersistentObjectStorage	db
long	oid
static int	PO_DELETED
static int	PO_LOADED
static int	PO_NEW
static int	PO_STUB
int	state
java.lang.Object	type

Constructor Summary

Persistent()

Method Summary

long	assignOID(PersistentObjectStorage db) Assign a persistent object identifier to the object, if it hasn't been assigned yet.
void	become(Persistent obj) Exchange references between objects in the database.
void	beginUpdate()
void	endUpdate()
Persistent	get() Load stub object from the database.
static Persistent	get(Persistent obj) Load stub object from the database.
long	getOid() Get the objects identifier.
static long	getOid(Persistent obj) Get the objects identifier.
ConsusRef	getRef() Get the objects JDBC reference.
static ConsusRef	getRef(Persistent obj) Get the JDBC reference to the object.
boolean	isDeleted() Check if the object is marked as deleted.
boolean	isLoaded() Check whether the object is a stub.
boolean	isNew() Check whether the object has not yet been stored in the database (assigned the persistent object identifier).
Persistent	load() Load stub object or reload the object from the database.
boolean	loadClosure() Specify whether the referenced objects should be loaded implicitly together with the parent object or not.
void	loadComponents() Load the components of the object.
void	lock() Lock database in exclusive mode.
void	remove() Remove the object from the database.
boolean	save() Store the object in the database if the deferredUpdate flag is 0.
void	store() Store the object attached to the database to the storage.
void	store(PersistentObjectStorage db) Save the object in the database.
java.lang.String	toString() Get the String representation of the persistent objects identifier.
void	unget() Clear all object fields (to make it possible for GC to collect unused persistent objects).

Methods inherited from class java.lang.Object

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

Field Detail

db

public transient PersistentObjectStorage db

oid

public transient long oid

PO_DELETED

public static final int PO_DELETED

See Also:

Constant Field Values

PO_LOADED

public static final int PO_LOADED

See Also:

Constant Field Values

PO_NEW

public static final int PO_NEW

See Also:

Constant Field Values

PO_STUB

public static final int PO_STUB

See Also:

Constant Field Values

state

public transient int state

type

public transient java.lang.Object type

Constructor Detail

Persistent

public Persistent()

Method Detail

assignOID

public long assignOID(PersistentObjectStorage db)

Assign a persistent object identifier to the object, if it hasn't been assigned yet.

Parameters:

db - connection to the database in which object should be allocated

become

public void become(Persistent obj)

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

Parameters:

obj - object which OID will be exchanged with this object

beginUpdate

public final void beginUpdate()

endUpdate

public final void endUpdate()

get

public Persistent get()

Load stub object from the database. If the object was already loaded, this method does nothing.

Returns:

pointer to this

get

public static Persistent get(Persistent obj)

Load stub object from the database. If the object was already loaded, this method does nothing. This method is static and checks its parameter for the null value.

Returns:

pointer to this

getOid

public long getOid()

Get the objects identifier.

Returns:

object identifier

getOid

public static long getOid(Persistent obj)

Get the objects identifier.

Parameters:

obj - object or null

Returns:

object identifier

getRef

public ConsusRef getRef()

Get the objects JDBC reference.

Returns:

reference to the object as ConsusRef class.

getRef

public static ConsusRef getRef(Persistent obj)

Get the JDBC reference to the object.

Parameters:

obj - object or null

Returns:

reference to the object as ConsusRef class.

isDeleted

public final boolean isDeleted()

Check if the object is marked as deleted.

Returns:

true if remove method was invoked for the object.

isLoaded

public final boolean isLoaded()

Check whether the object is a stub. A stub object has the same type as the normal object, but has no data loaded.

Returns:

true when object has not yet been loaded from the database, and instead of it a stub was created.

isNew

public final boolean isNew()

Check whether the object has not yet been stored in the database (assigned the persistent object identifier). An object is concidered new starting from its creation and until stored in the database.

Returns:

true if object has no assigned OID yet.

load

public Persistent load()

Load stub object or reload the object from the database.

Returns:

pointer to this

loadClosure

public boolean loadClosure()

Specify whether the referenced objects should be loaded implicitly together with the parent object or not. Default implementation of this method returns true, so the complete tree of objects will be loaded into memory. To prevent loading of all objects (and so exhausting the memory), redefine this method and return false. In this case you will have to load the components explicitly.

Returns:

true to load all graph with referenced objects or false for loading stubs instead of referenced object.

loadComponents

public void loadComponents()

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

lock

public void lock()

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

remove

public void remove()

Remove the object from the database.

save

public boolean save()

Store the object in the database if the deferredUpdate flag is 0. deferredUpdate flag indicates that the object will be saved by the caller.

Returns:

true if method stores the object, false otherwise

store

public void store()

Store the object attached to the database to the storage. If object has not yet been assigned to the database, this method does nothing.

store

public void store(PersistentObjectStorage db)

Save the object in the database. If the object refers to some some other persistent-capable objects without assigned object identifiers, then these objects will also be recursively saved in the database.

toString

public java.lang.String toString()

Get the String representation of the persistent objects identifier.

Overrides:

toString in class java.lang.Object

Returns:

class name '@' OID

unget

public void unget()

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