net.sourceforge.jfacefactories.presenters
Class AbstractPresenter<T>

java.lang.Object
  net.sourceforge.jfacefactories.presenters.AbstractPresenter<T>

public class AbstractPresenter<T>
extends java.lang.Object

Parent for 'Presenter' classes that wrap domain objects as java beans and add UI logic as additional properties.
The wrapped domain object is of type T.
The domain object should be modified through the following protected mutator methods that ensure that events are properly propagated:

• setDomainObjectValue
• addToDomainObjectCollection()
• removeFromDomainObjectCollection()
• editedDomainObjectCollectionElement()
• setPresenterValue()

This parent class introduces standard properties for use by the UI. By default these are:

• IS_CHANGED - a boolean
• IS_SAVEABLE - a boolean
• CHANGES - a list of PropertyChangeEvent's

Standard properties are recalculated every time any other property is changed, and changes events for these fired if necessary.
Additional standard properties can be added via addStandardProperty().

Presenter instances can be linked.
A Presenter can be instantiated as a 'child' of the an existing Presenter.
Events relating to the standard properties are automatically forwarded to the parent Presenter.
A child Presenter can optionally listen for events fired by any other children of its parent via 'sibling' listeners.

Presenters can access nested properties of the domain objects that they wrap by mapping a presenter property to a nested domain object property - see addPropertyMapping() for more.

Use of this class should be as follows;

1. Subtype the class using one or both of the supplied constructors;
2. Customise the subtype behaviour if necessary through calls to set-up methods addStandardProperty(), addPropertyMapping() and setExceptionHandler();
3. Define persistence behaviour by implementing doPreSave(), doSave() and doPostSave() as necessary;
4. Create getters for the necessary domain object properties that simply delegate to the the wrapped domain object;
5. Create setters for the necessary domain object properties that use the protected mutator methods listed above;
6. Add additional properties direct to the subclass to describe GUI behaviour

Since:

0.1

Author:

MikeE

Field Summary

static java.lang.String	CHANGES One of the standard properties.
static java.lang.String	IS_CHANGED One of the standard properties.
static java.lang.String	IS_SAVEABLE One of the standard properties.

Constructor Summary

protected	AbstractPresenter(AbstractPresenter<T> parent) Constructor for presenter that has a parent model.
protected	AbstractPresenter(T domainObject) Constructor for presenter that does not have a parent model.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Alerts the passed listener to any property changes on the Presenter.
void	addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Alerts the passed listener to any property changes relating to the passed property on the Presenter.
protected void	addPropertyMapping(java.lang.String modelProperty, java.lang.String domainObjectProperty) Adds a mapping between a presentation model property and the domain object's property.
protected void	addSiblingPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Alerts the passed listener to any property changes relating to the passed property on any other child presenter of this instance's parent presenter.
protected void	addStandardProperty(java.lang.String property) Adds a standard property (see class javadoc for more).
protected void	addToDomainObjectCollection(java.lang.String propertyName, java.lang.Object newElement) Add the passed element to the Collection property identified by the passed property name.
protected void	addToDomainObjectCollection(java.lang.String propertyName, java.lang.Object newElement, java.lang.String... listenerProperties) Add the passed element to the Collection property identified by the passed property name.
protected boolean	doIsSaveable() Default method simply returns true.
protected void	doPostSave() Subclasses can override if they have post-save actions.
protected boolean	doPreSave() Default method simply returns true.
protected boolean	doSave() Default method simply returns true.
protected void	editedDomainObjectCollectionElement(java.lang.String propertyName, java.lang.Object changedElement) Records that an element of a collection property has been changed.
protected void	editedDomainObjectCollectionElement(java.lang.String propertyName, java.lang.Object changedElement, java.lang.String... listenerProperties) Records that an element of a collection property has been changed.
java.util.List<java.beans.PropertyChangeEvent>	getChanges() Returns the recorded property changes on the domain object since the last save.
protected T	getDomainObject() Accessor to the domain model.
boolean	isChanged() Public property - whether the domain object has been changed or not.
boolean	isSaveable() Public property - whether the domain object can be saved.
protected void	removeFromDomainObjectCollection(java.lang.String propertyName, java.lang.Object newElement) Removes the passed element from the Collection property identified by the passed property name.
protected void	removeFromDomainObjectCollection(java.lang.String propertyName, java.lang.Object newElement, java.lang.String... listenerProperties) Removes the passed element from the Collection property identified by the passed property name.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes the listener
void	removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Removes the listener
protected void	removeSiblingPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Removes the listener.
void	rollback() Clears all changes, resetting the model and the domain object to their state after their last save (or initialisation).
void	save() Causes the following sequence of calls: calls doPreSave() - if this returns false stops calls doPreSave() on each child - if any returns false stops immediately calls doSave() - if this returns false stops calls doSave() on each child - if any returns false stops immediately calls doPostSave() calls doPostSave() on each child Each implemented method in this sequence must handle its own errors, simply returning false to indicate the save process must terminate.
protected void	setDomainObjectValue(java.lang.String propertyName, java.lang.Object newValue) Sets the value for the passed property on the domain object if it has changed where there are no associated calculated values affected Fires all standard property listeners; This also records the change and (potentially) marks the model as dirty.
protected void	setDomainObjectValue(java.lang.String propertyName, java.lang.Object newValue, java.lang.String... listenerProperties) Sets the value for the passed property on the domain object if it has changed.
void	setExceptionHandler(IExceptionHandler handler) Sets the exception handler for save and setter operations.
protected void	setPresenterValue(java.lang.String propertyName, java.lang.Object newValue) Sets the value for a passed property on the presenter (as opposed to the underlying domain object).
protected void	setPresenterValue(java.lang.String propertyName, java.lang.Object newValue, java.lang.String... listenerProperties) Sets the value for a passed property on the presenter (as opposed to the underlying domain object).

Methods inherited from class java.lang.Object

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

Field Detail

IS_CHANGED

public static final java.lang.String IS_CHANGED

One of the standard properties.
The name of the boolean property describing whether the wrapped domain object has been changed since the last save. Note this is based on the CHANGES property so will report the domain object as changed even if the changes result in the domain object back in its original state.

See Also:

Constant Field Values

IS_SAVEABLE

public static final java.lang.String IS_SAVEABLE

One of the standard properties.
The name of the boolean property describing whether the wrapped domain object can be saved or not.

See Also:

Constant Field Values

CHANGES

public static final java.lang.String CHANGES

One of the standard properties.
The name of a List of PropertyChangeEvents which lists the changes to the domain object since the last save.
To support undo/redo behaviour this a chronological list of all changes so even if the domain object is set back to its original state the interim changes are listed.

See Also:

Constant Field Values

Constructor Detail

AbstractPresenter

protected AbstractPresenter(AbstractPresenter<T> parent)

Constructor for presenter that has a parent model.

Parameters:

perent - - cannot be null.

AbstractPresenter

protected AbstractPresenter(T domainObject)

Constructor for presenter that does not have a parent model.

Parameters:

domainObject - - cannot be null.

Method Detail

addPropertyMapping

protected final void addPropertyMapping(java.lang.String modelProperty,
                                        java.lang.String domainObjectProperty)

Adds a mapping between a presentation model property and the domain object's property. Hence addPropertyMapping( "A", "B" ) would mean that the presentation model operates on a property called "A" but whenever it updates the domain object, it updates the property name "B". This is primarily for use in nested properties; ie. a presenter property such as 'companyPhone' mapped to the domain object property 'company.phone.number'.

Parameters:

modelProperty -

domainObjectProperty -

addStandardProperty

protected final void addStandardProperty(java.lang.String property)

Adds a standard property (see class javadoc for more).

Parameters:

property - - cannot be null and must not already have been added.

See Also:

AbstractPresenter

setExceptionHandler

public final void setExceptionHandler(IExceptionHandler handler)

Sets the exception handler for save and setter operations.
If null is passed reset to the default exception handler that simply throws a runtime exception and/or assert out.

Parameters:

handler -

addPropertyChangeListener

public final void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Alerts the passed listener to any property changes on the Presenter.
Note the listener will also be alerted to any standard property changes on any children of this presenter.

Parameters:

listener -

See Also:

PropertyChangeSupport.addPropertyChangeListener(java.beans.PropertyChangeListener)

addPropertyChangeListener

public final void addPropertyChangeListener(java.lang.String propertyName,
                                            java.beans.PropertyChangeListener listener)

Alerts the passed listener to any property changes relating to the passed property on the Presenter. If the property is one of the standard properties the listener will also be alerted of any events on child presenters of this instance.

Parameters:

propertyName -

listener -

See Also:

PropertyChangeSupport.addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)

removePropertyChangeListener

public final void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes the listener

Parameters:

listener -

See Also:

PropertyChangeSupport.removePropertyChangeListener(java.beans.PropertyChangeListener)

removePropertyChangeListener

public final void removePropertyChangeListener(java.lang.String propertyName,
                                               java.beans.PropertyChangeListener listener)

Removes the listener

Parameters:

propertyName -

listener -

See Also:

PropertyChangeSupport.removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)

isChanged

public final boolean isChanged()

Public property - whether the domain object has been changed or not.

Returns:

See Also:

IS_CHANGED

isSaveable

public boolean isSaveable()

Public property - whether the domain object can be saved.
This default method simply returns true but subclasses might override this - note they should call super.
If this has children, any one of them that cannot be saved will cause this to return false

Returns:

getChanges

public final java.util.List<java.beans.PropertyChangeEvent> getChanges()

Returns the recorded property changes on the domain object since the last save.
Note that the list returned is an unmodifiable copy of the presenter's internal state.

Returns:

See Also:

CHANGES

save

public final void save()

Causes the following sequence of calls:

1. calls doPreSave() - if this returns false stops
2. calls doPreSave() on each child - if any returns false stops immediately
3. calls doSave() - if this returns false stops
4. calls doSave() on each child - if any returns false stops immediately
5. calls doPostSave()
6. calls doPostSave() on each child

Each implemented method in this sequence must handle its own errors, simply returning false to indicate the save process must terminate.

rollback

public final void rollback()

Clears all changes, resetting the model and the domain object to their state after their last save (or initialisation).
Calls rollback() on all child presenters.

Throws:

java.lang.Exception

setDomainObjectValue

protected final void setDomainObjectValue(java.lang.String propertyName,
                                          java.lang.Object newValue)

Sets the value for the passed property on the domain object if it has changed where there are no associated calculated values affected
Fires all standard property listeners;
This also records the change and (potentially) marks the model as dirty.

Parameters:

property - - cannot be null

newValue - - can be null

setDomainObjectValue

protected final void setDomainObjectValue(java.lang.String propertyName,
                                          java.lang.Object newValue,
                                          java.lang.String... listenerProperties)

Sets the value for the passed property on the domain object if it has changed.
Fires all standard property listeners and any for the passed properties;
This also records the change and (potentially) marks the model as dirty.

Parameters:

property - - cannot be null

newValue - - can be null

listenerProperties - - other properties for which listeners should be fired if their values change

addToDomainObjectCollection

protected final void addToDomainObjectCollection(java.lang.String propertyName,
                                                 java.lang.Object newElement)

Add the passed element to the Collection property identified by the passed property name.
Fires all standard property listeners;
This also records the change and (potentially) marks the model as dirty.
Note that most collection manipulation is done directly via databinding - this method is intended only for use where different controls affect the same collection (e.g. a 'remove' button next to a list)

Parameters:

property -

newElement -

addToDomainObjectCollection

protected final void addToDomainObjectCollection(java.lang.String propertyName,
                                                 java.lang.Object newElement,
                                                 java.lang.String... listenerProperties)

Add the passed element to the Collection property identified by the passed property name.
Fires all standard property listeners and any for the passed properties;
This also records the change and (potentially) marks the model as dirty.
Note that most collection manipulation is done directly via databinding - this method is intended only for use where different controls affect the same collection (e.g. a 'remove' button next to a list)

Parameters:

property -

newElement -

listenerProperties - - other properties for which listeners should be fired if their values change

removeFromDomainObjectCollection

protected final void removeFromDomainObjectCollection(java.lang.String propertyName,
                                                      java.lang.Object newElement)

Removes the passed element from the Collection property identified by the passed property name.
Fires all standard property listeners;
This also records the change and (potentially) marks the model as dirty.
Note that most collection manipulation is done directly via databinding - this method is intended only for use where different controls affect the same collection (e.g. a 'remove' button next to a list)

Parameters:

property -

newElement -

removeFromDomainObjectCollection

protected final void removeFromDomainObjectCollection(java.lang.String propertyName,
                                                      java.lang.Object newElement,
                                                      java.lang.String... listenerProperties)

Removes the passed element from the Collection property identified by the passed property name.
Fires all standard property listeners and any for the passed properties;
This also records the change and (potentially) marks the model as dirty.
Note that most collection manipulation is done directly via databinding - this method is intended only for use where different controls affect the same collection (e.g. a 'remove' button next to a list)

Parameters:

property -

newElement -

listenerProperties - - other properties for which listeners should be fired if their values change

editedDomainObjectCollectionElement

protected final void editedDomainObjectCollectionElement(java.lang.String propertyName,
                                                         java.lang.Object changedElement)

Records that an element of a collection property has been changed.
Fires all property listeners;
This also records the change and (potentially) marks the model as dirty.
Note that most collection manipulation is done directly via databinding - this method is intended only for use where external code edits an element of a collection that the model would otherwise not know about.

Parameters:

propertyName -

changedElement -

editedDomainObjectCollectionElement

protected final void editedDomainObjectCollectionElement(java.lang.String propertyName,
                                                         java.lang.Object changedElement,
                                                         java.lang.String... listenerProperties)

Records that an element of a collection property has been changed.
Fires all property listeners;
This also records the change and (potentially) marks the model as dirty.
Note that most collection manipulation is done directly via databinding - this method is intended only for use where external code edits an element of a collection that the model would otherwise not know about.

Parameters:

propertyName -

changedElement -

listenerProperties - - other properties for which listeners should be fired if their values change

setPresenterValue

protected final void setPresenterValue(java.lang.String propertyName,
                                       java.lang.Object newValue)

Sets the value for a passed property on the presenter (as opposed to the underlying domain object).
This also records the change and (potentially) marks the model as dirty.

Parameters:

property - - cannot be null

newValue - - can be null

setPresenterValue

protected final void setPresenterValue(java.lang.String propertyName,
                                       java.lang.Object newValue,
                                       java.lang.String... listenerProperties)

Sets the value for a passed property on the presenter (as opposed to the underlying domain object).
Fires all standard property listeners and any for the passed properties;
This also records the change and (potentially) marks the model as dirty.

Parameters:

property - - cannot be null

newValue - - can be null

listenerProperties - - other properties for which listeners should be fired if their values change

addSiblingPropertyChangeListener

protected final void addSiblingPropertyChangeListener(java.lang.String propertyName,
                                                      java.beans.PropertyChangeListener listener)

Alerts the passed listener to any property changes relating to the passed property on any other child presenter of this instance's parent presenter.
This will throw an IllegalStateException() if the instance was not instantiated with a parent presenter.

Parameters:

propertyName -

listener -

See Also:

PropertyChangeSupport.addPropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)

removeSiblingPropertyChangeListener

protected final void removeSiblingPropertyChangeListener(java.lang.String propertyName,
                                                         java.beans.PropertyChangeListener listener)

Removes the listener.
This will throw an IllegalStateException() if the instance was not instantiated with a parent presenter.

Parameters:

propertyName -

listener -

See Also:

PropertyChangeSupport.removePropertyChangeListener(java.lang.String, java.beans.PropertyChangeListener)

getDomainObject

protected T getDomainObject()

Accessor to the domain model.
Not final as subclasses may want to make public (though not recommended).

Returns:

the domainObject

doIsSaveable

protected boolean doIsSaveable()

Default method simply returns true.
Subclasses can override to affect the isSaveable() property.

Returns:

true

See Also:

isSaveable()

doPreSave

protected boolean doPreSave()

Default method simply returns true.
Subclasses can override if they have pre-save actions.
Any error must be dealt with internally and simply reported as a false return.

Returns:

true

See Also:

save()

doSave

protected boolean doSave()

Default method simply returns true.
Subclasses can override if they have save actions.
Any error must be dealt with internally and simply reported as a false return.

Returns:

true

See Also:

save()

doPostSave

protected void doPostSave()

Subclasses can override if they have post-save actions.
Any error must be dealt with internally and will not prevent other doPostSave() calls being made.

See Also:

save()