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

Interface UiDataBinding<VALUE>

Type Parameters:

VALUE - is the generic type of the value.

All Superinterfaces:

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

All Known Implementing Classes:

AbstractUiDataBinding, UiDataBindingDatatype, UiDataBindingList, UiDataBindingNone, UiDataBindingPojo, UiDataBindingPojoComposite

public interface UiDataBinding<VALUE>
extends UiFeatureValueAndValidation<VALUE>, AttributeWriteModified

This is the interface for the data-binding for values with widgets.
Important:
Regular users should only use the data-binding for UiWidgetCustomComposite and derived classes where it allows comfortable property-bindings.
Have a look at the following example:

 public class MyBeanFrom extends UiWidgetCustomGridPanel {

   public MyBeanForm(UiContext context) {
     super(context, MyBean.class);
     UiWidgetWithValue<Integer> fooField = getDataBinding().createAndBind(MyBean.PROPERTY_FOO);
     getDelegate().addChildren(fooField);
     UiWidgetWithValue<BarType> barField = getDataBinding().createAndBind(MyBean.PROPERTY_BAR);
     getDelegate().addChildren(barField);
     ...
   }
 }
 

With MyBean like this:

 public class MyBean implements Pojo {

   public static final TypedProperty<Integer> PROPERTY_FOO = new TypedProperty<>("foo");
   public static final TypedProperty<BarType> PROPERTY_BAR = new TypedProperty<>("bar");

    @Min(-5)
    @Max(5)
   private int foo;

    @Mandatory
   private BarType bar;

   public int getFoo() {
     return this.foo;
   }

   public void setFoo(int foo) {
     this.foo = foo;
   }

   public BarType getBar() {
     return this.bar;
   }

   public void setBar(BarType bar) {
     this.bar = bar;
   }

   ...

 }
 

This will automatically do all the nasty work for you as described in createAndBind(TypedProperty) . Otherwise you would have to do something like this in your widget:

 public class MyBeanFrom extends UiWidgetCustomGridPanel {

   private final UiWidgetIntegerField fooField;

   private final MyBarCustomWidget barField;

   public MyBeanForm(UiContext context) {
     super(context, MyBean.class);
     // create field for property "foo" by hand...
     this.fooField = getContext().getWidgetFactory().create(UiWidgetIntegerField.class);
     Integer min = Integer.valueOf(-5);
     this.fooField.setMinimumValue(min);
     Integer max = Integer.valueOf(5);
     this.fooField.setMaximumValue(max);
     NlsBundleMyLabelsRoot labels = NlsAccess.getBundleFactory().createBundle(NlsBundleMyLabelsRoot.class);
     this.fooField.setLabel(labels.foo());
     this.fooField.addValidator(new ValidatorRange<Integer>(min, max));
     this.fooField.addValidator(ValidatorMandatory.getInstance());
     getDelegate().addChildren(this.fooField);
     // create field for property "bar" by hand...
     this.barField = new MyBarCustomWidget(context);
     this.barField.setLabel(labels.bar());
     this.barField.addValidator(ValidatorMandatory.getInstance());
     getDelegate().addChildren(this.barField);
     ...
   }

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
<P> void	bind(TypedProperty<P> property, UiWidgetWithValue<P> widget) 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 createAndBind(TypedProperty) but using the given label instead of deriving it automatically.
PropertyAccessor<VALUE,?>	createPropertyAccessor(String property)
<P> PropertyAccessor<VALUE,P>	createPropertyAccessor(TypedProperty<P> property)
boolean	doValidate(ValidationState state, VALUE value) This method performs the actual validation using the registered validators.
String	getLabel(TypedProperty<?> property) Determines the label to use for the given property (including I18N, etc.).
VALUE	getRecentValue()
Boolean	getValidity()
void	setValidity(Boolean validity) This method sets the value of getValidity().

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

getValueAndValidate, getValueDirect

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

addChangeHandler, removeChangeHandler

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

resetValue, setValue, setValue, setValueForUser

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

getOriginalValue, 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

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

setModified

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

isModified

Method Detail

bind

<P> void bind(TypedProperty<P> property,
              UiWidgetWithValue<P> widget)

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.

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

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

See Also:

createAndBind(TypedProperty)

createAndBind

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

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

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

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

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.

getValidity

Boolean getValidity()

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

void setValidity(Boolean validity)

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

Parameters:

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

doValidate

boolean doValidate(ValidationState state,
                   VALUE value)

This method performs the actual validation using the registered validators. It is called from AbstractUiWidget (method doValidate) that itself is called from AbstractValidatableObject.validate(ValidationState).

Parameters:

state - is the ValidationState. Must NOT be null.

value - is the current value of this object that has already be determined.

Returns:

true if the validation was successful, false otherwise (if there are validation failures).

getRecentValue

VALUE getRecentValue()

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.

createPropertyAccessor

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

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

createPropertyAccessor

PropertyAccessor<VALUE,?> createPropertyAccessor(String property)

Parameters:

property - is the property name.

Returns:

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

getLabel

String getLabel(TypedProperty<?> property)

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

Parameters:

property - is the TypedProperty.

Returns:

the label to use for the property.

See Also:

TypedProperty.getTitle()