org.jaffa.persistence
Class Persistent

java.lang.Object
  org.jaffa.persistence.Persistent

All Implemented Interfaces:

Cloneable, IPersistent, Serializable

Direct Known Subclasses:

ValidFieldValue

public abstract class Persistent

extends Object

implements IPersistent

Base class for all persistent objects.

See Also:

Serialized Form

Constructor Summary

Persistent()

Method Summary

protected IPersistent	actualInstance() This method simply returns the 'this' object.
protected void	addInitialValue(String fieldName, Object initialValue) Adds an initial value for a field whenever it is modified.
Object	clone() Returns a clone of the object.
int	getLocking() Returns the locking strategy for this persistent object.
UOW	getUOW() Returns the UOW to which this object is associated.
boolean	isDatabaseOccurence() Returns a true value if the object was loaded from the database.
boolean	isLocked() Returns a true value if the underlying database row is locked.
boolean	isModified() Returns a true value if the object had any of its fields updated.
boolean	isModified(String fieldName) Returns a true value if the field has been updated.
boolean	isQueued() Returns a true value if this object has been added/updated/deleted and not yet been committed.
void	performForeignKeyValidations() This method ensures that the modified foreign-keys are valid.
void	performPreDeleteReferentialIntegrity() This method will perform referential integrity checks before this object is deleted.
void	postAdd() This method is triggered by the UOW, after adding this object to the Add-Store.
void	postDelete() This method is triggered by the UOW, after adding this object to the Delete-Store.
void	postLoad() This method is triggered by the UOW after a query loads this object.
void	postUpdate() This method is triggered by the UOW, after adding this object to the Update-Store.
void	preAdd() This method is triggered by the UOW, before adding this object to the Add-Store, but after a UOW has been associated to the object.
void	preDelete() This method is triggered by the UOW, before adding this object to the Delete-Store.
void	preUpdate() This method is triggered by the UOW, before adding this object to the Update-Store.
Object	returnInitialValue(String fieldName) Returns the initial value for a field; i.e. before it was modified.
void	setDatabaseOccurence(boolean databaseOccurence) Set the database status of this object.
void	setLocked(boolean locked) Set the locked status of this object.
void	setLocking(int locking) Set the locking strategy for this persistent object.
void	setModified(boolean modified) Set the modified status of this object.
void	setQueued(boolean queued) Set the queued status of this object.
void	setUOW(UOW uow) Associates this object to a UOW.
String	toString() This returns the state of the object for diagnostic purposes.
protected void	update() This method should be invoked by every updateXxx() method of the persistent class, before setting the value.

Methods inherited from class java.lang.Object

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

Constructor Detail

Persistent

public Persistent()

Method Detail

toString

public String toString()

This returns the state of the object for diagnostic purposes.

Returns:

a String representation of the object.

clone

public Object clone()
             throws CloneNotSupportedException

Returns a clone of the object.

Returns:

a clone of the object.

Throws:

CloneNotSupportedException - if cloning is not supported. This should never happen.

getUOW

public UOW getUOW()

Returns the UOW to which this object is associated.

Specified by:

getUOW in interface IPersistent

Returns:

The UOW

setUOW

public void setUOW(UOW uow)

Associates this object to a UOW. Note: This method is for internal use by the Persistence Engine only.

Specified by:

setUOW in interface IPersistent

Parameters:

uow - The UOW.

isModified

public boolean isModified()

Returns a true value if the object had any of its fields updated.

Specified by:

isModified in interface IPersistent

Returns:

a true value if the object had any of its fields updated.

setModified

public void setModified(boolean modified)

Set the modified status of this object. Note: This method is for internal use by the Persistence Engine only.

Specified by:

setModified in interface IPersistent

Parameters:

modified - the modified status.

isDatabaseOccurence

public boolean isDatabaseOccurence()

Returns a true value if the object was loaded from the database.

Specified by:

isDatabaseOccurence in interface IPersistent

Returns:

a true value if the object was loaded from the database.

setDatabaseOccurence

public void setDatabaseOccurence(boolean databaseOccurence)

Set the database status of this object. Note: This method is for internal use by the Persistence Engine only.

Specified by:

setDatabaseOccurence in interface IPersistent

Parameters:

databaseOccurence - the database status.

getLocking

public int getLocking()

Returns the locking strategy for this persistent object.

Specified by:

getLocking in interface IPersistent

Returns:

the locking strategy for this persistent object.

setLocking

public void setLocking(int locking)

Set the locking strategy for this persistent object. Note: This method is for internal use by the Persistence Engine only.

Specified by:

setLocking in interface IPersistent

Parameters:

locking - the locking strategy.

isLocked

public boolean isLocked()

Returns a true value if the underlying database row is locked.

Specified by:

isLocked in interface IPersistent

Returns:

a true value if the underlying database row is locked.

setLocked

public void setLocked(boolean locked)

Set the locked status of this object. Note: This method is for internal use by the Persistence Engine only.

Specified by:

setLocked in interface IPersistent

Parameters:

locked - the locked status.

isQueued

public boolean isQueued()

Returns a true value if this object has been added/updated/deleted and not yet been committed.

Specified by:

isQueued in interface IPersistent

Returns:

a true value if this object has been added/updated/deleted and not yet been committed.

setQueued

public void setQueued(boolean queued)

Set the queued status of this object. The Persistence Engine will set the queued status to true on an Add/Update/Delete. Thereafter, any updates on this object will throw a RuntimeException. This flag will be reset after the object actaully gets added/updated/deleted to the database. Note: This method is for internal use by the Persistence Engine only.

Specified by:

setQueued in interface IPersistent

Parameters:

queued - the queued status.

isModified

public boolean isModified(String fieldName)

Returns a true value if the field has been updated.

Specified by:

isModified in interface IPersistent

Parameters:

fieldName - the field to check.

Returns:

a true value if the field has been updated.

returnInitialValue

public Object returnInitialValue(String fieldName)

Returns the initial value for a field; i.e. before it was modified. A null will be returned if the field was never modified. Use the isModified() method to determine if the field was modified. A null will also be returned, if the field had a null value to begin with.

Specified by:

returnInitialValue in interface IPersistent

Parameters:

fieldName - the field.

Returns:

the initial value for a field; i.e. before it was modified.

preAdd

public void preAdd()
            throws PreAddFailedException

This method is triggered by the UOW, before adding this object to the Add-Store, but after a UOW has been associated to the object. This will perform the following tasks: Will invoke the PersistentHelper.exists() to check against duplicate keys. Will invoke the performForeignKeyValidations() method to ensure no invalid foreign-keys are set. Will invoke PersistentHelper.checkMandatoryFields() to perform mandatory field checks. Will invoke the Rules Engine to perform mandatory field checks.

Specified by:

preAdd in interface IPersistent

Throws:

PreAddFailedException - if any error occurs during the process.

postAdd

public void postAdd()
             throws PostAddFailedException

This method is triggered by the UOW, after adding this object to the Add-Store. A concrete persistent object should provide the implementation, if its necessary.

Specified by:

postAdd in interface IPersistent

Throws:

PostAddFailedException - if any error occurs during the process.

preUpdate

public void preUpdate()
               throws PreUpdateFailedException

This method is triggered by the UOW, before adding this object to the Update-Store. This will perform the following tasks: Will invoke the performForeignKeyValidations() method to ensure no invalid foreign-keys are set. Will invoke PersistentHelper.checkMandatoryFields() to perform mandatory field checks. Will invoke the Rules Engine to perform mandatory field checks.

Specified by:

preUpdate in interface IPersistent

Throws:

PreUpdateFailedException - if any error occurs during the process.

postUpdate

public void postUpdate()
                throws PostUpdateFailedException

This method is triggered by the UOW, after adding this object to the Update-Store. A concrete persistent object should provide the implementation, if its necessary.

Specified by:

postUpdate in interface IPersistent

Throws:

PostUpdateFailedException - if any error occurs during the process.

preDelete

public void preDelete()
               throws PreDeleteFailedException

This method is triggered by the UOW, before adding this object to the Delete-Store. This will perform the following tasks: Will invoke the performPreDeleteReferentialIntegrity() method.

Specified by:

preDelete in interface IPersistent

Throws:

PreDeleteFailedException - if any error occurs during the process.

postDelete

public void postDelete()
                throws PostDeleteFailedException

This method is triggered by the UOW, after adding this object to the Delete-Store. A concrete persistent object should provide the implementation, if its necessary.

Specified by:

postDelete in interface IPersistent

Throws:

PostDeleteFailedException - if any error occurs during the process.

postLoad

public void postLoad()
              throws PostLoadFailedException

This method is triggered by the UOW after a query loads this object. A concrete persistent object should provide the implementation, if its necessary.

Specified by:

postLoad in interface IPersistent

Throws:

PostLoadFailedException - if any error occurs during the process.

performForeignKeyValidations

public void performForeignKeyValidations()
                                  throws ApplicationExceptions,
                                         FrameworkException

This method ensures that the modified foreign-keys are valid. A concrete persistent object should provide the implementation, if its necessary.

Throws:

ApplicationExceptions - if an invalid foreign key is set.

FrameworkException - Indicates some system error

performPreDeleteReferentialIntegrity

public void performPreDeleteReferentialIntegrity()
                                          throws PreDeleteFailedException

This method will perform referential integrity checks before this object is deleted. This will cascade delete all composite objects. This will raise an exception if any associated/aggregated objects exist. A concrete persistent object should provide the implementation, if its necessary.

Throws:

PreDeleteFailedException - if any error occurs during the process.

update

protected void update()
               throws ReadOnlyObjectException,
                      AlreadyLockedObjectException,
                      IllegalPersistentStateRuntimeException

This method should be invoked by every updateXxx() method of the persistent class, before setting the value. It ensures that a readonly object cannot be updated. It acquires a lock for the pessimistic locking strategy. Finally, it sets the modified flag.

Throws:

ReadOnlyObjectException - if the object has been marked as ReadOnly, and hence cannot be updated.

AlreadyLockedObjectException - if the object has been locked by another process.

IllegalPersistentStateRuntimeException - this RuntimeException will be thrown if the domain object has been submitted to the UOW for an Add/Update/Delete and commit hasnt yet been performed.

addInitialValue

protected void addInitialValue(String fieldName,
                               Object initialValue)

Adds an initial value for a field whenever it is modified. This method is typically invoked by the updateXyz() method of the extending class. Note: The value will not be added, if the field has already been modified.

Parameters:

fieldName - the field.

initialValue - the initial value.

actualInstance

protected IPersistent actualInstance()

This method simply returns the 'this' object. A proxy implementation will override this method and return the proxy instance.

Returns:

the persistent instance.