org.caleigo.core
Class AbstractEntity

java.lang.Object
  org.caleigo.core.AbstractEntity

All Implemented Interfaces:

java.lang.Comparable, IDataConsumer, IDataProvider, IDistributable, IEntity, java.io.Serializable

Direct Known Subclasses:

AbstractDataObjectEntity

public abstract class AbstractEntity

extends java.lang.Object

implements IEntity

The AbstractEntity class is an abtsract implementation of the IEntity interface. Subclasses only need to override the tree methods getRawData, setRawData and getEntityDescriptor. Entities are data objects representing single instances of data rows/records from a persistent data storage. An entity contains several fields of data accessible using the setData() and getData() methods.

Version:

1.00

Author:

Dennis Zikovic

See Also:

Serialized Form

Field Summary

Fields inherited from interface org.caleigo.core.IEntity

DIRTY, EMPTY, PERSISTENT

Constructor Summary

AbstractEntity()
Default constructor for AbstractEntity.

AbstractEntity(Qualifier identityQualifier)

Method Summary

void	addEntityChangeListener(IEntityChangeListener listener) Adds IEntityChangeListener to receive notifications of changes in the entity's status and data content.
void	addEntityListener(IEntityListener listener) Adds IEntityListener to receive notifications of performed data operations on the entity object.
void	clear() Clear resets all data in the entity to their defalt values and sets the flags to reflect an empty unchanged data entity.
protected void	clearAllDirtyFlags()
void	clearStatusFlag(int flags) Should not normally be used by standard API users.
int	compareTo(java.lang.Object entity) Compares all identity data values between the objects if they are of the same type that is are defined by the same entity descriptor.
void	copyData(IDataProvider propertySource) Copies and updates the in the entity containde data by reading each individual data field as a property from the provided property source.
void	delete() This method will delete the entity from it's related persistent storage.
protected void	doOnDataChange(IFieldDescriptor fieldDescriptor, java.lang.Object oldValue, java.lang.Object newValue) This help method is called when the called entity changes a data value.
protected void	doOnDirty() This help method is called when the called when an entity changes state from non-dirty to dirty.
protected void	doOnStateChange(int statusType, boolean newStatus) This help method is called when the called entity changes state.
boolean	equals(java.lang.Object entity) Returns true if the data in all the entities IDENTIY fields are considered equal according to their DataType class.
boolean	equalsExactly(java.lang.Object entity) Compares all data values between the objects if they are of the same type.
protected void	fireDataChangedEvent(IFieldDescriptor fieldDescriptor, java.lang.Object oldValue, java.lang.Object newValue) Fires an EntityChangeEvent specifying a data field change to all registered IEntityChangeListener objects.
protected void	fireOpPerformedEvent(int opType) Fires an EntityEvent with the provided operation type to all registered IEntityListener objects.
protected void	fireStatusChangedEvent(int statusType, boolean newStatus) Fires an EntityChangeEvent specifying a status change to all registered IEntityChangeListener objects.
java.lang.Object	getData(IFieldDescriptor fieldDescriptor) Returns the data value of the addressed data field.
java.lang.Object	getData(java.lang.String codeName) Access method the returns the identified data from the object.
boolean	getDataBoolean(IFieldDescriptor field)
byte	getDataByte(IFieldDescriptor field)
double	getDataDouble(IFieldDescriptor field)
float	getDataFloat(IFieldDescriptor field)
int	getDataInteger(IFieldDescriptor field)
long	getDataLong(IFieldDescriptor field)
short	getDataShort(IFieldDescriptor field)
IDataSource	getDataSource() Returns the data source that the entity object belongs to.
abstract IEntityDescriptor	getEntityDescriptor() Return the entity objects IEntityDescriptor that defines it's type and structure.
Qualifier	getOriginQualifier() Returns a identity qualifier that uniquely qualifies the entity in a persistent storage.
(package private) abstract java.lang.Object	getRawData(int index) Should return the contained indexed data avoidinng any convertions or formating.
boolean	isDataNull(IFieldDescriptor fieldDescriptor) Returns true if the addressed entity field is contains a NULL value.
boolean	isDirty() Returns true if any entity field in the entity has been changed since creation or the last syncronization with the persistent storage.
boolean	isEmpty() Returns true for newly creted object that that has had no changes from the default data set at the moment of creation.
boolean	isFieldDirty(IFieldDescriptor fieldDescriptor) Returns true if the addressed entity field has been changed since creation or the last syncronization with the persistent storage.
boolean	isPersistent() Returns true if the the entity reflects data that exists in a related persistent storage.
static java.lang.String	makeLogString(IEntity entity) Makes a descriptive log string for the provided entity object.
static java.lang.String	makeLogString(IEntity entity, IFieldDescriptor[] fields) Makes a descriptive log string for the provided entity object.
void	refresh() This method will refresh the entity with current data from the related persistent storage.
void	removeEntityChangeListener(IEntityChangeListener listener) Removes the specified IEntityListener from the entity object.
void	removeEntityListener(IEntityListener listener) Removes the specified IEntityListener from the entity object.
void	setData(IDataProvider dataProvider) This method implies to the called object to fetch all data it can consume from the provided IDataProvider object.
void	setData(IFieldDescriptor fieldDescriptor, java.lang.Object data) Sets the value of the addressed data field.
void	setData(java.lang.String codeName, java.lang.Object dataValue) Sets the data identified by the provided code name.
void	setDataBoolean(IFieldDescriptor field, boolean value)
void	setDataByte(IFieldDescriptor field, byte value)
void	setDataDouble(IFieldDescriptor field, double value)
void	setDataFloat(IFieldDescriptor field, float value)
void	setDataInteger(IFieldDescriptor field, int value)
void	setDataLong(IFieldDescriptor field, long value)
void	setDataShort(IFieldDescriptor field, short value)
protected void	setDefaultValues() This method is expected to set the default values to the entity.
protected void	setDirtyFlag(IFieldDescriptor fieldDescriptor)
(package private) abstract void	setRawData(int index, java.lang.Object data) Should set the indexed data avoiding any convertions or format changes.
void	setStatusFlag(int flags) Should not normally be used by standard API users.
void	store() This method will store any unsaved changes in the entity to it's realated persistent storage.
java.lang.String	toString() Overriden to display the entity description type, identifying data and state of the status flags (D)IRTY, (E)MPTY and (P)ERSISTANT.
ValidationResult	validateData() Help method that validates the data contained in the called data object and returns a ValidationResult object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractEntity

public AbstractEntity()

Default constructor for AbstractEntity.

AbstractEntity

public AbstractEntity(Qualifier identityQualifier)

Method Detail

makeLogString

public static java.lang.String makeLogString(IEntity entity)

Makes a descriptive log string for the provided entity object. Will only display the data from the identity fields.

makeLogString

public static java.lang.String makeLogString(IEntity entity,
                                             IFieldDescriptor[] fields)

Makes a descriptive log string for the provided entity object. Will only display the data for the provided field descriptors.

getEntityDescriptor

public abstract IEntityDescriptor getEntityDescriptor()

Return the entity objects IEntityDescriptor that defines it's type and structure. Enables extended means of reflection for the entity.

Specified by:

getEntityDescriptor in interface IEntity

getRawData

abstract java.lang.Object getRawData(int index)

Should return the contained indexed data avoidinng any convertions or formating. Note the package scope used to avoid missuse.

setRawData

abstract void setRawData(int index,
                         java.lang.Object data)

Should set the indexed data avoiding any convertions or format changes. Must not update any flags or fire any event handled by the AbstractEntityDescriptor. Note the package scope used to avoid missuse.

toString

public java.lang.String toString()

Overriden to display the entity description type, identifying data and state of the status flags (D)IRTY, (E)MPTY and (P)ERSISTANT.

store

public void store()

This method will store any unsaved changes in the entity to it's realated persistent storage. This will reset the DIRTY flag and set the PERSISTENT flag.

Specified by:

store in interface IEntity

delete

public void delete()

This method will delete the entity from it's related persistent storage. This will set the DIRTY flag and reset the PERSISTENT flag. Note that that the actual java object will not be deleted or changed in any other way besides its status changes makeing possible to recreate the object by simply calling the store() method.

Specified by:

delete in interface IEntity

refresh

public void refresh()

This method will refresh the entity with current data from the related persistent storage. All contained data with any existing changes will be replaced from the storage. This will reset the DIRTY flag and can possibly reset the PERSISTENT flag if the entity can no longer be found in the related database/storage.

Specified by:

refresh in interface IEntity

copyData

public void copyData(IDataProvider propertySource)

Copies and updates the in the entity containde data by reading each individual data field as a property from the provided property source. Note that since IEntity extends the IDataProvider interface it is thereby possibli to copy other entities with this method. Even if the etities are not of the same type all fields with the same name will be copied into the entity. Identical data will not be copied and if any changes were made the DIRTY flag will be set. Will use the copyData method defined be each fields DataType object to copy the data which also controls if the copy is shallow or not.

Specified by:

copyData in interface IEntity

isDataNull

public boolean isDataNull(IFieldDescriptor fieldDescriptor)

Returns true if the addressed entity field is contains a NULL value.

Specified by:

isDataNull in interface IEntity

getData

public java.lang.Object getData(IFieldDescriptor fieldDescriptor)

Returns the data value of the addressed data field. Can return NULL if the field excepts and contains a NULL value.

Specified by:

getData in interface IEntity

Throws:

InvalidFieldException

setData

public void setData(IFieldDescriptor fieldDescriptor,
                    java.lang.Object data)

Sets the value of the addressed data field. Sets the DIRTY flag and clears the EMPTY flag but only if the new value differs from the old. If the value is actually changed then one or more EntityChangeExceptions will be fired.

Specified by:

setData in interface IEntity

Throws:

InvalidFieldException

ReadOnlyViolationException

clear

public void clear()

Clear resets all data in the entity to their defalt values and sets the flags to reflect an empty unchanged data entity.

Specified by:

clear in interface IEntity

validateData

public ValidationResult validateData()

Help method that validates the data contained in the called data object and returns a ValidationResult object. Call isValid on the returned object to verify data validity. May never return null.

Specified by:

validateData in interface IEntity

isFieldDirty

public boolean isFieldDirty(IFieldDescriptor fieldDescriptor)

Returns true if the addressed entity field has been changed since creation or the last syncronization with the persistent storage.

Specified by:

isFieldDirty in interface IEntity

isDirty

public boolean isDirty()

Returns true if any entity field in the entity has been changed since creation or the last syncronization with the persistent storage.

Specified by:

isDirty in interface IEntity

isEmpty

public boolean isEmpty()

Returns true for newly creted object that that has had no changes from the default data set at the moment of creation.

Specified by:

isEmpty in interface IEntity

isPersistent

public boolean isPersistent()

Returns true if the the entity reflects data that exists in a related persistent storage. This means that newly created and deleted entities will have this flag set to false.

Specified by:

isPersistent in interface IEntity

getDataSource

public IDataSource getDataSource()

Returns the data source that the entity object belongs to. Newly created will normally return the default data source defined by the IDataSourceDescriptor that the entity is linked to trough it's IEntityDescriptor. Entities loaded from a persistent storage will return the data source that identifies that storage/database.

Specified by:

getDataSource in interface IEntity

getOriginQualifier

public Qualifier getOriginQualifier()

Returns a identity qualifier that uniquely qualifies the entity in a persistent storage. If the entity is PERSISTENT and any of the data in the identity fields have changed since the storage syncronization the returned Qualifier will identify the stored persistent version of the entity and NOT& the updated local one.

Specified by:

getOriginQualifier in interface IEntity

equals

public boolean equals(java.lang.Object entity)

Returns true if the data in all the entities IDENTIY fields are considered equal according to their DataType class.

Specified by:

equals in interface IEntity

equalsExactly

public boolean equalsExactly(java.lang.Object entity)

Compares all data values between the objects if they are of the same type. True is returned only if all contained data exactly matches the compareded entity's data according to their DataType class.

Specified by:

equalsExactly in interface IEntity

getData

public java.lang.Object getData(java.lang.String codeName)

Description copied from interface: IDataProvider

Access method the returns the identified data from the object.

Specified by:

getData in interface IDataProvider

setData

public void setData(java.lang.String codeName,
                    java.lang.Object dataValue)

Description copied from interface: IDataConsumer

Sets the data identified by the provided code name.

Specified by:

setData in interface IDataConsumer

setData

public void setData(IDataProvider dataProvider)

Description copied from interface: IDataConsumer

This method implies to the called object to fetch all data it can consume from the provided IDataProvider object.

Specified by:

setData in interface IDataConsumer

compareTo

public int compareTo(java.lang.Object entity)

Compares all identity data values between the objects if they are of the same type that is are defined by the same entity descriptor.

If the compared object is not an IEntity object a ClassCastException will be thrown. If the object is an IEntity but of another type, that is described by another entity descriptor, then the entities will first be ordered according to type using the order MASTER_ENTITY, SLAVE_ENTITY, LINK_ENTITY, STATIC_ENTITY, CUSTOM_ENTITY and secondly according to the entity descriptors code name.

Specified by:

compareTo in interface java.lang.Comparable

setStatusFlag

public void setStatusFlag(int flags)

Description copied from interface: IEntity

Should not normally be used by standard API users. Would have been protected if the Java language spec allowed it.

Specified by:

setStatusFlag in interface IEntity

clearStatusFlag

public void clearStatusFlag(int flags)

Description copied from interface: IEntity

Should not normally be used by standard API users. Would have been protected if the Java language spec allowed it.

Specified by:

clearStatusFlag in interface IEntity

addEntityListener

public void addEntityListener(IEntityListener listener)

Adds IEntityListener to receive notifications of performed data operations on the entity object.

Specified by:

addEntityListener in interface IEntity

removeEntityListener

public void removeEntityListener(IEntityListener listener)

Removes the specified IEntityListener from the entity object.

Specified by:

removeEntityListener in interface IEntity

addEntityChangeListener

public void addEntityChangeListener(IEntityChangeListener listener)

Adds IEntityChangeListener to receive notifications of changes in the entity's status and data content. Note that changes can in specific situations like during end-user editation be very frequent.

Specified by:

addEntityChangeListener in interface IEntity

removeEntityChangeListener

public void removeEntityChangeListener(IEntityChangeListener listener)

Removes the specified IEntityListener from the entity object.

Specified by:

removeEntityChangeListener in interface IEntity

setDefaultValues

protected void setDefaultValues()

This method is expected to set the default values to the entity. By default the values will set using the default values specified by the entity´s descriptor. The method can be overriden to set dynamic and runtime specific values.

doOnDataChange

protected void doOnDataChange(IFieldDescriptor fieldDescriptor,
                              java.lang.Object oldValue,
                              java.lang.Object newValue)

This help method is called when the called entity changes a data value. It is called before the data change event is fired. The method is provided for optional override and does nothing by default. Note that setting other data as a response to the change will cause a new call to this method! This requires any overrides to take care not to cause a reqursive loop by being very selective when updating data values in this method.

doOnDirty

protected void doOnDirty()

This help method is called when the called when an entity changes state from non-dirty to dirty. It is called before the status change event is fired. The method is provided for optional override and does nothing by default.

doOnStateChange

protected void doOnStateChange(int statusType,
                               boolean newStatus)

This help method is called when the called entity changes state. It is called before the status change event is fired. The method is provided for optional override and does nothing by default.

setDirtyFlag

protected void setDirtyFlag(IFieldDescriptor fieldDescriptor)

clearAllDirtyFlags

protected void clearAllDirtyFlags()

fireOpPerformedEvent

protected void fireOpPerformedEvent(int opType)

Fires an EntityEvent with the provided operation type to all registered IEntityListener objects.

fireDataChangedEvent

protected void fireDataChangedEvent(IFieldDescriptor fieldDescriptor,
                                    java.lang.Object oldValue,
                                    java.lang.Object newValue)

Fires an EntityChangeEvent specifying a data field change to all registered IEntityChangeListener objects.

fireStatusChangedEvent

protected void fireStatusChangedEvent(int statusType,
                                      boolean newStatus)

Fires an EntityChangeEvent specifying a status change to all registered IEntityChangeListener objects.

getDataLong

public long getDataLong(IFieldDescriptor field)

setDataLong

public void setDataLong(IFieldDescriptor field,
                        long value)

getDataInteger

public int getDataInteger(IFieldDescriptor field)

setDataInteger

public void setDataInteger(IFieldDescriptor field,
                           int value)

getDataShort

public short getDataShort(IFieldDescriptor field)

setDataShort

public void setDataShort(IFieldDescriptor field,
                         short value)

getDataByte

public byte getDataByte(IFieldDescriptor field)

setDataByte

public void setDataByte(IFieldDescriptor field,
                        byte value)

getDataBoolean

public boolean getDataBoolean(IFieldDescriptor field)

setDataBoolean

public void setDataBoolean(IFieldDescriptor field,
                           boolean value)

getDataFloat

public float getDataFloat(IFieldDescriptor field)

setDataFloat

public void setDataFloat(IFieldDescriptor field,
                         float value)

getDataDouble

public double getDataDouble(IFieldDescriptor field)

setDataDouble

public void setDataDouble(IFieldDescriptor field,
                          double value)