net.sf.mmm.client.ui.base.binding

Class AbstractUiDataBinding<VALUE>

java.lang.Object

net.sf.mmm.client.ui.base.feature.AbstractUiFeatureValueAndValidation<VALUE>

net.sf.mmm.client.ui.base.feature.AbstractUiFeatureValueAndValidationWithValidators<VALUE>

net.sf.mmm.client.ui.base.binding.AbstractUiDataBinding<VALUE>

Type Parameters:

VALUE - is the generic type of the value.

All Implemented Interfaces:

AttributeReadModified, AttributeReadValueAdvanced<VALUE>, AttributeWriteModified, AttributeWriteValueAdvanced<VALUE>, UiFeature, UiFeatureValidation<VALUE>, UiFeatureValue<VALUE>, UiFeatureValueAndValidation<VALUE>, UiDataBinding<VALUE>, AttributeReadValue<VALUE>, AttributeWriteValue<VALUE>, AbstractValidatableObject, HasValueValidators<VALUE>, ValidatableObject<VALUE>

Direct Known Subclasses:

UiDataBindingDatatype, UiDataBindingList, UiDataBindingPojo

public abstract class AbstractUiDataBinding<VALUE>
extends AbstractUiFeatureValueAndValidationWithValidators<VALUE>
implements UiDataBinding<VALUE>

This is a base implementation of UiDataBinding.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	modified
private VALUE	originalValue
private VALUE	recentValue
private Boolean	validity
private AbstractUiWidget<VALUE>	widget

Constructor Summary

Constructors

Constructor and Description
AbstractUiDataBinding(AbstractUiWidget<VALUE> widget) The constructor.

Method Summary

Modifier and Type	Method and Description
void	addChangeHandler(UiHandlerEventValueChange<VALUE> handler) This method adds the given UiHandlerEventValueChange to this object.
<P> void	bind(TypedProperty<P> property, UiWidgetWithValue<P> valueWidget) This method binds the given widget to the given property.
<P> UiWidgetWithValue<P>	createAndBind(TypedProperty<P> property) This method creates a value based widget that is to be added as child of the widget owning this data-binding.
<P> UiWidgetWithValue<P>	createAndBind(TypedProperty<P> property, String label) This method is like UiDataBinding.createAndBind(TypedProperty) but using the given label instead of deriving it automatically.
protected abstract VALUE	createCopyOfValue(VALUE value) This method will create a (deep-)copy of the given value.
protected abstract VALUE	createNewValue() This method creates a new instance of <VALUE> (see AbstractUiFeatureValueAndValidation.getValue()).
PropertyAccessor<VALUE,?>	createPropertyAccessor(String property)
<P> PropertyAccessor<VALUE,P>	createPropertyAccessor(TypedProperty<P> property)
protected ValidationFailure	createValidationFailure(Throwable error) This method converts an exception from AbstractUiFeatureValueAndValidation.getValueOrException(Object) to a ValidationFailure.
protected VALUE	doGetValue(VALUE template, ValidationState state) This method is called from AbstractUiFeatureValueAndValidation.getValueOrException(Object).
protected void	doSetValue(VALUE value, boolean forUser) This method is called from setValue(Object, boolean).
String	getLabel(TypedProperty<?> property) Determines the label to use for the given property (including I18N, etc.).
protected org.slf4j.Logger	getLogger()
VALUE	getOriginalValue() This method gets the last value that has been set.
VALUE	getRecentValue()
protected String	getSource()
Boolean	getValidity()
VALUE	getValueDirect(VALUE template, ValidationState state) This method is a combination of AttributeReadValueAdvanced.getValueOrException(Object) and AbstractValidatableObject.validate(ValidationState).
protected AbstractUiWidget<VALUE>	getWidget()
boolean	isModified() This method determines if this object (or more precisely its value) is modified.
boolean	removeChangeHandler(UiHandlerEventValueChange<VALUE> handler) This method removes the given UiHandlerEventValueChange from this object.
protected void	setMandatory(boolean mandatory)
void	setModified(boolean modified) This method sets the modified attribute programatically.
void	setValidity(Boolean validity) This method sets the value of UiDataBinding.getValidity().
void	setValue(VALUE newValue, boolean forUser) This is the generic variant of AttributeWriteValueAdvanced.setValue(Object) and AttributeWriteValueAdvanced.setValueForUser(Object).
String	toString()

Methods inherited from class net.sf.mmm.client.ui.base.feature.AbstractUiFeatureValueAndValidationWithValidators

addValidator, doValidate, isMandatory, isMandatory, removeValidator

Methods inherited from class net.sf.mmm.client.ui.base.feature.AbstractUiFeatureValueAndValidation

addValidatorMandatory, clearValidity, getValue, getValueAndValidate, getValueOrException, handleGetValueError, resetValue, setValue, setValueForUser, validate

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.mmm.client.ui.base.binding.UiDataBinding

doValidate

Methods inherited from interface net.sf.mmm.client.ui.api.feature.UiFeatureValueAndValidation

getValueAndValidate

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeWriteValueAdvanced

resetValue, setValue, setValueForUser

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadValueAdvanced

getValue, getValueOrException

Methods inherited from interface net.sf.mmm.client.ui.api.feature.UiFeatureValidation

addValidatorMandatory, isMandatory

Methods inherited from interface net.sf.mmm.util.validation.api.HasValueValidators

addValidator, removeValidator

Methods inherited from interface net.sf.mmm.util.validation.api.AbstractValidatableObject

validate

Field Detail

widget

private final AbstractUiWidget<VALUE> widget

See Also:

getWidget()

originalValue

private VALUE originalValue

See Also:

getOriginalValue()

recentValue

private VALUE recentValue

See Also:

getRecentValue()

modified

private boolean modified

See Also:

isModified()

validity

private Boolean validity

See Also:

getValidity()

Constructor Detail

AbstractUiDataBinding

public AbstractUiDataBinding(AbstractUiWidget<VALUE> widget)

The constructor.

Parameters:

widget - is the widget to bind.

Method Detail

getWidget

protected final AbstractUiWidget<VALUE> getWidget()

Returns:

the AbstractUiWidget bound via this UiDataBinding.

getLogger

protected final org.slf4j.Logger getLogger()

Specified by:

getLogger in class AbstractUiFeatureValueAndValidation<VALUE>

Returns:

a Logger instance.

setValue

public final void setValue(VALUE newValue,
                           boolean forUser)

This is the generic variant of AttributeWriteValueAdvanced.setValue(Object) and AttributeWriteValueAdvanced.setValueForUser(Object).
NOTE:
To make your code expressive please only use this method for generic situations where forUser is dynamic.

Specified by:

setValue in interface AttributeWriteValueAdvanced<VALUE>

Parameters:

newValue - is the new value to set.

forUser - true for the semantics of AttributeWriteValueAdvanced.setValueForUser(Object), false for AttributeWriteValueAdvanced.setValue(Object).

doSetValue

protected void doSetValue(VALUE value,
                          boolean forUser)

This method is called from setValue(Object, boolean). It has to be implemented with the custom logic to set the value in the view. The implementation of this method has to correspond with the implementation of doGetValue(Object, ValidationState).

Parameters:

value - is the value to set. Typically a composite object (e.g. java bean) so its attributes are set to fields (see UiWidgetField).

forUser - true if called from AbstractUiFeatureValueAndValidation.setValueForUser(Object), false if set from AbstractUiFeatureValueAndValidation.setValue(Object).

See Also:

doGetValue(Object, ValidationState)

getValueDirect

public final VALUE getValueDirect(VALUE template,
                                  ValidationState state)
                           throws RuntimeException

This method is a combination of AttributeReadValueAdvanced.getValueOrException(Object) and AbstractValidatableObject.validate(ValidationState). It allows more efficient implementations as determining and creating the value can be expensive. Saving changes requires validation AND on success getting the value, while already validation requires getting the value. For composite UI objects this effect would reinforce to multiply the number of calls to AttributeReadValueAdvanced.getValueOrException(Object).
NOTE:
This method is designed for implementors of composite UI objects. API users should only use UiFeatureValueAndValidation.getValueAndValidate(ValidationState).

Specified by:

getValueDirect in interface UiFeatureValueAndValidation<VALUE>

Parameters:

template - is the object where the data is filled in. May also be null - then this method will create a new instance.

state - is the ValidationState. If null the validation will be omitted, otherwise an implicit validation is performed.

Returns:

the current value. May be null (esp. if invalid).

Throws:

RuntimeException - if state is null no validation is performed and input errors are directly thrown causing a fast fail. Otherwise if validation is performed all RuntimeException are catched and according validation failures are collected and visualized by the UI.

createNewValue

protected abstract VALUE createNewValue()

This method creates a new instance of <VALUE> (see AbstractUiFeatureValueAndValidation.getValue()). It is called from getValueDirect(Object, ValidationState) or AbstractUiFeatureValueAndValidation.setValue(Object) in case the given value is null.
NOTE:
If <VALUE> is Void or a Datatype (immutable object), this method should legally return null. This can also be suitable for objects that only delegate their value to something else. Further, to be GWT compatible you cannot create the new instance via reflection. If you do not care about GWT, you can use reflection or better use it via PojoFactory.

Returns:

a new instance of <VALUE>.

createCopyOfValue

protected abstract VALUE createCopyOfValue(VALUE value)

This method will create a (deep-)copy of the given value.
ATTENTION:
If <VALUE> is immutable you can simply return null.

Parameters:

value - is the value to copy. Will typically be getOriginalValue(). Must NOT be modified in any way.

Returns:

a copy of the value or null if NOT implemented or supported.

doGetValue

protected VALUE doGetValue(VALUE template,
                           ValidationState state)

This method is called from AbstractUiFeatureValueAndValidation.getValueOrException(Object). It has to be implemented with the custom logic to get the value from the view. The implementation of this method has to correspond with the implementation of doSetValue(Object, boolean). A typical implementation of this method for a composite widget should look like this:

Parameters:

template - is the object where the data is filled in. May only be null if createNewValue() does.

state - is the ValidationState. May be null (if the validation is omitted). Should only be used to propagate to getValueDirect(Object, ValidationState) of children.

Returns:

the current value of this widget. May be null if empty. If <VALUE> is String the empty String has to be returned if no value has been entered. In case <VALUE> is a mutable object (java bean) and template is NOT null, this method is supposed to return template after the value(s) of this object have been assigned. If template is null this method has to create a new instance of <VALUE>. It is forbidden and an explicit bug-pattern to modify the original value. This is required to support operations such as AbstractUiFeatureValueAndValidation.resetValue().

See Also:

doSetValue(Object, boolean)

getOriginalValue

public final VALUE getOriginalValue()

This method gets the last value that has been set. After calling AttributeWriteValueAdvanced.setValue(Object) the value can be modified (by the user in case of a widget). Then calls to AttributeReadValueAdvanced.getValue() will return the current value with its potential modifications (as a new object). This method will ensure to get the value that was set before by the program.
ATTENTION:
The original value shall never be modified to avoid undesired side effects. Various features such as AttributeWriteValueAdvanced.resetValue() rely on this fact. Therefore AttributeReadValueAdvanced.getValue() will always return a new instance.

Specified by:

getOriginalValue in interface AttributeReadValueAdvanced<VALUE>

Returns:

the original value.

getRecentValue

public VALUE getRecentValue()

Specified by:

getRecentValue in interface UiDataBinding<VALUE>

Returns:

the last value that has been set via AttributeWriteValueAdvanced.setValue(Object, boolean). This is the original value or the value that has been set for the user after the original value was set for the last time.

isModified

public boolean isModified()

This method determines if this object (or more precisely its value) is modified. This means that the object has been modified (via a the user interface) since it's value was programatically set for the last time. Often this is also called dirty. A composite object is also modified if one of its children are modified.
NOTE:
If the object's value is changed by the end-user to something else but then changed back to its original value it may still remain modified.

Specified by:

isModified in interface AttributeReadModified

Returns:

true if this object has been modified, false otherwise (if no changes have been made to this object).

See Also:

AttributeReadValueAdvanced.getOriginalValue(), AttributeWriteValueAdvanced.setValueForUser(Object)

setModified

public void setModified(boolean modified)

This method sets the modified attribute programatically.
ATTENTION:
This interface and this method is NOT intended to be used by API users. The strategy how to determine if something is modified should be an implementation secret (another strategy may be to get the value and check if it is equal to the original value what is however not as robust). Instead methods such as AttributeWriteValueAdvanced.setValueForUser(Object) should be provided for API users.

Specified by:

setModified in interface AttributeWriteModified

Parameters:

modified - is the new value of AttributeReadModified.isModified().

See Also:

AttributeReadModified.isModified()

getValidity

public Boolean getValidity()

Specified by:

getValidity in interface UiDataBinding<VALUE>

Returns:

Boolean.TRUE if validation was successful, Boolean.FALSE if validation failed, null if NOT validated (since UiFeatureMessages.clearMessages() or something similar has been called).

setValidity

public void setValidity(Boolean validity)

This method sets the value of UiDataBinding.getValidity().
ATTENTION:
This is an internal method and should NOT be used by external users. Usage has to be compliant with UiDataBinding.getValidity().

Specified by:

setValidity in interface UiDataBinding<VALUE>

Parameters:

validity - is the new value for UiDataBinding.getValidity(). May be null.

setMandatory

protected void setMandatory(boolean mandatory)

Overrides:

setMandatory in class AbstractUiFeatureValueAndValidationWithValidators<VALUE>

Parameters:

mandatory - is the mandatory to set

createValidationFailure

protected ValidationFailure createValidationFailure(Throwable error)

This method converts an exception from AbstractUiFeatureValueAndValidation.getValueOrException(Object) to a ValidationFailure.

Overrides:

createValidationFailure in class AbstractUiFeatureValueAndValidation<VALUE>

Parameters:

error - is the exception.

Returns:

the ValidationFailure.

addChangeHandler

public void addChangeHandler(UiHandlerEventValueChange<VALUE> handler)

This method adds the given UiHandlerEventValueChange to this object.

Specified by:

addChangeHandler in interface UiFeatureValue<VALUE>

Parameters:

handler - is the UiHandlerEventValueChange to add.

removeChangeHandler

public boolean removeChangeHandler(UiHandlerEventValueChange<VALUE> handler)

This method removes the given UiHandlerEventValueChange from this object.

Specified by:

removeChangeHandler in interface UiFeatureValue<VALUE>

Parameters:

handler - is the UiHandlerEventValueChange to remove.

Returns:

true if the handler has been removed successfully, false if it was NOT registered and nothing has changed.

bind

public <P> void bind(TypedProperty<P> property,
                     UiWidgetWithValue<P> valueWidget)

This method binds the given widget to the given property. This will have to following effects:

• UiFeatureValueAndValidation.getValueDirect(Object, net.sf.mmm.util.validation.api.ValidationState) and therefore all other getValue* methods will automatically read the value of the given widget and set it to the given property of the <VALUE> to return.
• AttributeWriteValueAdvanced.setValue(Object, boolean) and therefore all other setValue* methods will automatically get the property-value of the given property from the <VALUE>-object and set that property-value to the given widget.

Specified by:

bind in interface UiDataBinding<VALUE>

Type Parameters:

P - is the generic type of the property value.

Parameters:

property - is the TypedProperty representing the property to bind. It has to be a property of <VALUE>.

valueWidget - is the value based widget to bind to the given property.

See Also:

UiDataBinding.createAndBind(TypedProperty)

createAndBind

public <P> UiWidgetWithValue<P> createAndBind(TypedProperty<P> property)

This method creates a value based widget that is to be added as child of the widget owning this data-binding. This will have to following effects:

• A new widget is created according to the property type via UiWidgetFactoryDatatype and can be highly customized.
• The label is automatically derived from the property including localization. Therefore you need to define a NlsBundleWithLookup (see UiConfiguration.getLabelLookup()) mapping the title with the properties to the localized display labels.
• A ValueValidator is automatically created for the property based on JSR 303 and will be added to the new widget.
• Mandatory fields are marked as such (appearance can be customized in CSS).
• If the input field is a UiWidgetRangeField the minimum and maximum value is set in case JSR 303 constraints such as Min, DecimalMin, Max, and DecimalMax are present. In the example the property foo will be rendered as an integer spin box for the value range from -5 to +5.
• Also, primitive types are also automatically considered as mandatory as they can not be null.
• The new widget is automatically bound to the given property.

Specified by:

createAndBind in interface UiDataBinding<VALUE>

Type Parameters:

P - is the generic type of the property value.

Parameters:

property - is the TypedProperty representing the property to bind. It has to be a property of <VALUE> and contain its property type.

Returns:

a new widget to view and edit the given property. It will already been bound.

createAndBind

public <P> UiWidgetWithValue<P> createAndBind(TypedProperty<P> property,
                                              String label)

This method is like UiDataBinding.createAndBind(TypedProperty) but using the given label instead of deriving it automatically.

Specified by:

createAndBind in interface UiDataBinding<VALUE>

Type Parameters:

P - is the generic type of the property value.

Parameters:

property - is the TypedProperty representing the property to bind. It has to be a property of <VALUE> and contain its property type.

label - is the label to use for the widget. See UiWidgetField.getLabel().

Returns:

a new widget to view and edit the given property. It will already been bound.

getLabel

public String getLabel(TypedProperty<?> property)

Determines the label to use for the given property (including I18N, etc.).

Specified by:

getLabel in interface UiDataBinding<VALUE>

Parameters:

property - is the TypedProperty.

Returns:

the label to use for the property.

See Also:

TypedProperty.getTitle()

createPropertyAccessor

public PropertyAccessor<VALUE,?> createPropertyAccessor(String property)

Specified by:

createPropertyAccessor in interface UiDataBinding<VALUE>

Parameters:

property - is the property name.

Returns:

a PropertyAccessor for the given property based on the Pojo type <VALUE>.

createPropertyAccessor

public <P> PropertyAccessor<VALUE,P> createPropertyAccessor(TypedProperty<P> property)

Specified by:

createPropertyAccessor in interface UiDataBinding<VALUE>

Type Parameters:

P - is the generic type of the property to access - see TypedProperty.getPropertyType().

Parameters:

property - is the TypedProperty.

Returns:

a PropertyAccessor for the given property based on the Pojo type <VALUE>.

getSource

protected String getSource()

Specified by:

getSource in class AbstractUiFeatureValueAndValidation<VALUE>

Returns:

the source for validation failures.

toString

public String toString()

Overrides:

toString in class AbstractUiFeatureValueAndValidation<VALUE>