org.caleigo.core
Interface IEntity

All Superinterfaces:

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

All Known Subinterfaces:

IProxyController, IProxyEntity

All Known Implementing Classes:

AbstractEntity, ProxyEntity

public interface IEntity

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

IEntity defines a basic interface for data objects representing a single instance of a data row/record from a persistent data storage. An entity contains several fields of data accessible using the setData() and getData() methods. Note that the contained fields are not defined as ordered by this interface and are instead adressed using their IFieldDescriptor.

Version:

1.00

Author:

Dennis Zikovic

Field Summary

static int	DIRTY Status flag that sinifies that an entity has unsaved changes since creation or last syncronization with the persistent storage.
static int	EMPTY Status flag that used for newly creted object that that has had no changes from the default data set at the moment of creation.
static int	PERSISTENT Status flag that is used to signify that the entity reflects data that exists in in a related persistent storage.

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.
void	clearStatusFlag(int flags) Should not normally be used by standard API users.
void	copyData(IDataProvider entitySource) Copies and replaces the, in the entity, contained 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.
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.
java.lang.Object	getData(IFieldDescriptor fieldDescriptor) Returns the data value of the addressed data field.
IDataSource	getDataSource() Returns the data source that the entity object belongs to.
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.
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.
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(IFieldDescriptor fieldDescriptor, java.lang.Object data) Sets the value of the addressed data field.
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.
ValidationResult	validateData() Help method that validates the data contained in the called data object and returns a ValidationResult object.

Methods inherited from interface org.caleigo.core.IDataProvider

getData

Methods inherited from interface org.caleigo.core.IDataConsumer

setData, setData

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

DIRTY

public static final int DIRTY

Status flag that sinifies that an entity has unsaved changes since creation or last syncronization with the persistent storage.

See Also:

Constant Field Values

EMPTY

public static final int EMPTY

Status flag that used for newly creted object that that has had no changes from the default data set at the moment of creation.

See Also:

Constant Field Values

PERSISTENT

public static final int PERSISTENT

Status flag that is used to signify that the entity reflects data that exists in in a related persistent storage. This means that newly created and deleted entities will have this flag set to false.

See Also:

Constant Field Values

Method Detail

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.

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.

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.

copyData

public void copyData(IDataProvider entitySource)

Copies and replaces the, in the entity, contained 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 possible 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.

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.

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.

isDataNull

public boolean isDataNull(IFieldDescriptor fieldDescriptor)

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

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.

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.

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.

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.

getEntityDescriptor

public IEntityDescriptor getEntityDescriptor()

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

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.

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.

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.

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.

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.

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.

setStatusFlag

public void setStatusFlag(int flags)

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

clearStatusFlag

public void clearStatusFlag(int flags)

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

addEntityListener

public void addEntityListener(IEntityListener listener)

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

removeEntityListener

public void removeEntityListener(IEntityListener listener)

Removes the specified IEntityListener from the entity object.

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.

removeEntityChangeListener

public void removeEntityChangeListener(IEntityChangeListener listener)

Removes the specified IEntityListener from the entity object.