org.caleigo.core
Class ProxyEntity

java.lang.Object
  org.caleigo.core.ProxyEntity

All Implemented Interfaces:

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

Direct Known Subclasses:

ControlledProxyEntity

public class ProxyEntity

extends java.lang.Object

implements IProxyEntity, IProxyController

A ProxyEntity is a basic implementation of the IProxyEntity iterface. The class acts as a proxy to another IEntity object that may set by simple access a methods. All events are forwarded transparently. Note that controlled proxies are transient and will not be serialized.

Version:

1.00

Author:

Dennis Zikovic

See Also:

Serialized Form

Nested Class Summary

protected class

ProxyEntity.ControlledProxyListener

Field Summary

Fields inherited from interface org.caleigo.core.IEntity

DIRTY, EMPTY, PERSISTENT

Constructor Summary

ProxyEntity(IEntity entity)
Creates new ProxyEntity

ProxyEntity(IEntityDescriptor descriptor)
Creates new ProxyEntity

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	addProxyListener(IProxyListener listener) Adds an IProxyListener to receive notifications of changes of the remote 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.
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 provider) 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.
void	doOnRemoteChange() This method is called each time the remote entity object are replaced.
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.
void	finalizeTransaction(boolean successful) The finalizeTransaction method is called after a transaction have been fully completed.
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	fireProxyEvent(int eventType) Fires a ProxyEvent with the provided operation type to all registered IProxyListener objects.
protected void	fireStatusChangedEvent(int statusType, boolean newStatus) Fires an EntityChangeEvent specifying a status change to all registered IEntityChangeListener objects.
java.util.Iterator	getControlledProxies() Returns an Iterator with all proxies currently controlled by the called controller.
IControlledProxy	getControlledProxy(IEntityDescriptor entityDescriptor, IEntityRelationPath relationPath) Returns an IControlledProxy object controlled by the called controller.
protected ProxyEntity.ControlledProxyListener	getControlledProxyListener() Help method that returns the selections slave change listener.
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.
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.
protected org.caleigo.core.ProxyEntity.RelayListener	getRelayListener() Help method that returns the selections relay listener.
IEntity	getRemoteEntity() Access method that returns the remote entity of the proxy.
IEntity	getSourceEntity() Access method that returns the source entity of the proxy.
protected boolean	hasDirtyControlledProxies()
boolean	hasRemoteEntity() Boolean access method that returns true if the proxy has a remote entity if false then getRemoteEntity() will return null.
boolean	hasSourceEntity() Boolean access method that returns true if the proxy has a source entity if false then getSourceEntity() will return null.
void	initializeEntity(IEntity entity, IEntityRelationPath relationPath) Help method that initializes the data in an entity object based on its relation to the controller.
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.
protected void	loadControlledProxies(boolean includeLocalRemote)
void	loadControlledProxiesCallback(int status)
void	prepareControlledLoad(IDataTransaction transaction) Prepares an transaction to load the proxy-chain structure that is controlled by the called IProxyController.
void	prepareControlledStore(IDataTransaction transaction) Prepares an transaction to store any changes made to the proxy-chain structure that is controlled by the called IProxyController.
void	refresh() This method will refresh the entity with current data from the related persistent storage.
void	releaseControlledProxy(IControlledProxy proxy) Used to inform the controller that a controlled proxy instance will be discarded and gives the controller a chance to deallocate resources connected to it.
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	removeProxyListener(IProxyListener listener) Removes the specified IProxyListener from the remote 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	setRemoteEntity(IEntity entity) Optional mutation method that throws an UnsupportedOperationException if the implementing class does not support the method.
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.
protected void	storeControlledProxies()
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.
protected void	updateDirtyState()
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

ProxyEntity

public ProxyEntity(IEntityDescriptor descriptor)

Creates new ProxyEntity

ProxyEntity

public ProxyEntity(IEntity entity)

Creates new ProxyEntity

Method Detail

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.

hasRemoteEntity

public boolean hasRemoteEntity()

Boolean access method that returns true if the proxy has a remote entity if false then getRemoteEntity() will return null.

Specified by:

hasRemoteEntity in interface IProxyEntity

getRemoteEntity

public IEntity getRemoteEntity()

Access method that returns the remote entity of the proxy. May return null if the proxy does not currently have a remote.

Specified by:

getRemoteEntity in interface IProxyEntity

hasSourceEntity

public boolean hasSourceEntity()

Boolean access method that returns true if the proxy has a source entity if false then getSourceEntity() will return null.

Specified by:

hasSourceEntity in interface IProxyEntity

getSourceEntity

public IEntity getSourceEntity()

Access method that returns the source entity of the proxy. May return null if the proxy does not currently have a source entity.

Specified by:

getSourceEntity in interface IProxyEntity

setRemoteEntity

public void setRemoteEntity(IEntity entity)

Optional mutation method that throws an UnsupportedOperationException if the implementing class does not support the method.

Specified by:

setRemoteEntity in interface IProxyEntity

addProxyListener

public void addProxyListener(IProxyListener listener)

Adds an IProxyListener to receive notifications of changes of the remote object.

Specified by:

addProxyListener in interface IProxyEntity

removeProxyListener

public void removeProxyListener(IProxyListener listener)

Removes the specified IProxyListener from the remote object.

Specified by:

removeProxyListener in interface IProxyEntity

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 provider)

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 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.

Specified by:

copyData 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

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. Should never return null.

Specified by:

validateData in interface IEntity

getEntityDescriptor

public 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

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

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.

Specified by:

setStatusFlag in interface IEntity

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.

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

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.

If the proxy does not have a remote it is compared with the provided entity using the default data values according to its type.

Specified by:

compareTo in interface java.lang.Comparable

getControlledProxy

public IControlledProxy getControlledProxy(IEntityDescriptor entityDescriptor,
                                           IEntityRelationPath relationPath)

Returns an IControlledProxy object controlled by the called controller. Implementing classes may cache the controlled proxies and return the same physical proxy object as long as the relationPath matches. The controller may refuse to controll a proxy and should then cast an IllegalArgumentException. If the used relation path does not link up the controller and the slave an InvalidRelationException is thrown.

Specified by:

getControlledProxy in interface IProxyController

releaseControlledProxy

public void releaseControlledProxy(IControlledProxy proxy)

Used to inform the controller that a controlled proxy instance will be discarded and gives the controller a chance to deallocate resources connected to it.

Specified by:

releaseControlledProxy in interface IProxyController

getControlledProxies

public java.util.Iterator getControlledProxies()

Returns an Iterator with all proxies currently controlled by the called controller.

Specified by:

getControlledProxies in interface IProxyController

prepareControlledLoad

public void prepareControlledLoad(IDataTransaction transaction)

Prepares an transaction to load the proxy-chain structure that is controlled by the called IProxyController.

Specified by:

prepareControlledLoad in interface IProxyController

prepareControlledStore

public void prepareControlledStore(IDataTransaction transaction)

Prepares an transaction to store any changes made to the proxy-chain structure that is controlled by the called IProxyController.

Specified by:

prepareControlledStore in interface IProxyController

finalizeTransaction

public void finalizeTransaction(boolean successful)

The finalizeTransaction method is called after a transaction have been fully completed. This method will always be called once after any call to prepareLoad or prepareStore.

initializeEntity

public void initializeEntity(IEntity entity,
                             IEntityRelationPath relationPath)

Help method that initializes the data in an entity object based on its relation to the controller.

Specified by:

initializeEntity in interface IProxyController

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

doOnRemoteChange

public void doOnRemoteChange()

This method is called each time the remote entity object are replaced. The method does by default load all controlled proxies.

hasDirtyControlledProxies

protected boolean hasDirtyControlledProxies()

loadControlledProxies

protected void loadControlledProxies(boolean includeLocalRemote)
                              throws DataServiceException

Throws:

DataServiceException

loadControlledProxiesCallback

public void loadControlledProxiesCallback(int status)

storeControlledProxies

protected void storeControlledProxies()
                               throws DataServiceException

Throws:

DataServiceException

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.

fireProxyEvent

protected void fireProxyEvent(int eventType)

Fires a ProxyEvent with the provided operation type to all registered IProxyListener objects.

getRelayListener

protected org.caleigo.core.ProxyEntity.RelayListener getRelayListener()

Help method that returns the selections relay listener. Can be overriden to customize the listener. Note that the method is contracted to allways return the same listener instance for a given ProxyEntity instance.

getControlledProxyListener

protected ProxyEntity.ControlledProxyListener getControlledProxyListener()

Help method that returns the selections slave change listener. Can be overriden to customize the listener. Note that the method is contracted to allways return the same listener instance for a given ProxyEntity instance.

updateDirtyState

protected void updateDirtyState()