Errai 3.0.1-SNAPSHOT

org.jboss.errai.databinding.client.api
Class DataBinder<T>

java.lang.Object
  extended by org.jboss.errai.databinding.client.api.DataBinder<T>
All Implemented Interfaces:
HasPropertyChangeHandlers

public class DataBinder<T>
extends Object
implements HasPropertyChangeHandlers

Provides an API to programmatically bind properties of a data model instance (any POJO annotated with Bindable) to UI fields/widgets. The properties of the model and the UI components will automatically be kept in sync for as long as they are bound.

Author:
Christian Sadilek

Method Summary
 void addPropertyChangeHandler(PropertyChangeHandler<?> handler)
          Adds a PropertyChangeHandler that will be notified when any property of the underlying object changes.
<P> void
addPropertyChangeHandler(String property, PropertyChangeHandler<P> handler)
          Adds a PropertyChangeHandler that will be notified when the given property of the underlying object changes.
 DataBinder<T> bind(com.google.gwt.user.client.ui.Widget widget, String property)
          Binds the provided widget to the specified property of the model instance associated with this DataBinder.
 DataBinder<T> bind(com.google.gwt.user.client.ui.Widget widget, String property, Converter converter)
          Binds the provided widget to the specified property of the model instance associated with this DataBinder.
static
<T> DataBinder<T>
forModel(T model)
          Creates a DataBinder for the provided model instance.
static
<T> DataBinder<T>
forModel(T model, InitialState initialState)
          Creates a DataBinder for the provided model instance, initializing either model or UI widgets from the values defined by InitialState.
static
<T> DataBinder<T>
forType(Class<T> modelType)
          Creates a DataBinder for a new model instance of the provided type.
static
<T> DataBinder<T>
forType(Class<T> modelType, InitialState initialState)
          Creates a DataBinder for a new model instance of the provided type, initializing either model or UI widgets from the values defined by InitialState.
 Set<String> getBoundProperties()
          Returns a set of the currently bound property names.
 T getModel()
          Returns the model instance associated with this DataBinder.
 List<com.google.gwt.user.client.ui.Widget> getWidgets(String property)
          Returns the widgets currently bound to the provided model property (see bind(Widget, String)).
 void removePropertyChangeHandler(PropertyChangeHandler<?> handler)
          Removes a PropertyChangeHandler, previously registered by a call to HasPropertyChangeHandlers.addPropertyChangeHandler(PropertyChangeHandler).
 void removePropertyChangeHandler(String property, PropertyChangeHandler<?> handler)
          Removes a PropertyChangeHandler, previously registered by a call to HasPropertyChangeHandlers.addPropertyChangeHandler(String, PropertyChangeHandler) for the same property name.
 T setModel(T model)
          Changes the underlying model instance.
 T setModel(T model, InitialState initialState)
          Changes the underlying model instance.
 T setModel(T model, InitialState initialState, boolean fireChangeEvents)
          Changes the underlying model instance.
 DataBinder<T> unbind()
          Unbinds all widgets bound by previous calls to #bind(HasValue, Object, String).
 DataBinder<T> unbind(String property)
          Unbinds all widgets bound to the specified model property by previous calls to #bind(HasValue, Object, String).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

forType

public static <T> DataBinder<T> forType(Class<T> modelType)
Creates a DataBinder for a new model instance of the provided type.

Parameters:
modelType - The bindable type, must not be null.

forType

public static <T> DataBinder<T> forType(Class<T> modelType,
                                        InitialState initialState)
Creates a DataBinder for a new model instance of the provided type, initializing either model or UI widgets from the values defined by InitialState.

Parameters:
modelType - The bindable type, must not be null.
initialState - Specifies the origin of the initial state of both model and UI widget. Null if no initial state synchronization should be carried out.

forModel

public static <T> DataBinder<T> forModel(T model)
Creates a DataBinder for the provided model instance.

Parameters:
model - The instance of a Bindable type, must not be null.

forModel

public static <T> DataBinder<T> forModel(T model,
                                         InitialState initialState)
Creates a DataBinder for the provided model instance, initializing either model or UI widgets from the values defined by InitialState.

Parameters:
model - The instance of a Bindable type, must not be null.
intialState - Specifies the origin of the initial state of both model and UI widget. Null if no initial state synchronization should be carried out.

bind

public DataBinder<T> bind(com.google.gwt.user.client.ui.Widget widget,
                          String property)
Binds the provided widget to the specified property of the model instance associated with this DataBinder. If the provided widget already participates in another binding managed by this DataBinder, a WidgetAlreadyBoundException will be thrown.

Parameters:
widget - The widget the model instance should be bound to, must not be null.
property - The name of the model property that should be used for the binding, following Java bean conventions. Chained (nested) properties are supported and must be dot (.) delimited (e.g. customer.address.street). Must not be null.
Returns:
the same DataBinder instance to support call chaining.
Throws:
NonExistingPropertyException - If the model does not have a property with the given name.
InvalidPropertyExpressionException - If the provided property chain expression is invalid.
WidgetAlreadyBoundException - If the provided widget is already bound to a property of the model.

bind

public DataBinder<T> bind(com.google.gwt.user.client.ui.Widget widget,
                          String property,
                          Converter converter)
Binds the provided widget to the specified property of the model instance associated with this DataBinder. If the provided widget already participates in another binding managed by this DataBinder, a WidgetAlreadyBoundException will be thrown.

Parameters:
widget - The widget the model instance should be bound to, must not be null.
property - The name of the model property that should be used for the binding, following Java bean conventions. Chained (nested) properties are supported and must be dot (.) delimited (e.g. customer.address.street). Must not be null.
converter - The converter to use for the binding, null if default conversion should be used (see Convert).
Returns:
the same DataBinder instance to support call chaining.
Throws:
NonExistingPropertyException - If the model does not have a property with the given name.
InvalidPropertyExpressionException - If the provided property chain expression is invalid.
WidgetAlreadyBoundException - If the provided widget is already bound to a property of the model.

unbind

public DataBinder<T> unbind(String property)
Unbinds all widgets bound to the specified model property by previous calls to #bind(HasValue, Object, String). This method has no effect if the specified property was never bound.

Parameters:
property - The name of the property (or a property chain) to unbind, Must not be null.
Returns:
the same DataBinder instance to support call chaining.
Throws:
InvalidPropertyExpressionException - If the provided property chain expression is invalid.

unbind

public DataBinder<T> unbind()
Unbinds all widgets bound by previous calls to #bind(HasValue, Object, String).

Returns:
the same DataBinder instance to support call chaining.

getModel

public T getModel()
Returns the model instance associated with this DataBinder.

Returns:
The model instance which has to be used in place of the provided model (see forModel(Object) and forType(Class)) if changes should be automatically synchronized with the UI.

setModel

public T setModel(T model)
Changes the underlying model instance. The existing bindings stay intact but only affect the new model instance. The previously associated model instance will no longer be kept in sync with the UI. The bound UI widgets will be updated based on the new model state.

Parameters:
model - The instance of a Bindable type, must not be null.
Returns:
The model instance which has to be used in place of the provided model (see forModel(Object) and forType(Class)) if changes should be automatically synchronized with the UI (also accessible using getModel()).

setModel

public T setModel(T model,
                  InitialState initialState)
Changes the underlying model instance. The existing bindings stay intact but only affect the new model instance. The previously associated model instance will no longer be kept in sync with the UI.

Parameters:
model - The instance of a Bindable type, must not be null.
initialState - Specifies the origin of the initial state of both model and UI widget. Null if no initial state synchronization should be carried out.
Returns:
The model instance which has to be used in place of the provided model (see forModel(Object) and forType(Class)) if changes should be automatically synchronized with the UI (also accessible using getModel()).

setModel

public T setModel(T model,
                  InitialState initialState,
                  boolean fireChangeEvents)
Changes the underlying model instance. The existing bindings stay intact but only affect the new model instance. The previously associated model instance will no longer be kept in sync with the UI.

Parameters:
model - The instance of a Bindable type, must not be null.
initialState - Specifies the origin of the initial state of both model and UI widget. Null if no initial state synchronization should be carried out.
fireChangeEvents - Specifies whether or not PropertyChangeEvents should be fired as a consequence of the model change.
Returns:
The model instance which has to be used in place of the provided model (see forModel(Object) and forType(Class)) if changes should be automatically synchronized with the UI (also accessible using getModel()).

getWidgets

public List<com.google.gwt.user.client.ui.Widget> getWidgets(String property)
Returns the widgets currently bound to the provided model property (see bind(Widget, String)).

Parameters:
property - The name of the property (or a property chain). Must not be null.
Returns:
the list of widgets currently bound to the provided property or an empty list if no widget was bound to the property.

getBoundProperties

public Set<String> getBoundProperties()
Returns a set of the currently bound property names.

Returns:
all bound properties, or an empty set if no properties have been bound.

addPropertyChangeHandler

public void addPropertyChangeHandler(PropertyChangeHandler<?> handler)
Description copied from interface: HasPropertyChangeHandlers
Adds a PropertyChangeHandler that will be notified when any property of the underlying object changes. Multiple handlers can be registered. If the same handler instance is passed multiple times, it will be notified multiple times.

Specified by:
addPropertyChangeHandler in interface HasPropertyChangeHandlers
Parameters:
handler - The PropertyChangeHandler instance, must not be null.

removePropertyChangeHandler

public void removePropertyChangeHandler(PropertyChangeHandler<?> handler)
Description copied from interface: HasPropertyChangeHandlers
Removes a PropertyChangeHandler, previously registered by a call to HasPropertyChangeHandlers.addPropertyChangeHandler(PropertyChangeHandler). If the handler was added more than once to the same event source, it will be notified one less time after being removed. If the provided handler is null, or was never added, no exception is thrown and no action is taken.

Specified by:
removePropertyChangeHandler in interface HasPropertyChangeHandlers
Parameters:
handler - the PropertyChangeHandler instance

addPropertyChangeHandler

public <P> void addPropertyChangeHandler(String property,
                                         PropertyChangeHandler<P> handler)
Description copied from interface: HasPropertyChangeHandlers
Adds a PropertyChangeHandler that will be notified when the given property of the underlying object changes. Multiple handlers can be registered. If the same handler instance is passed multiple times, it will be notified multiple times.

Specified by:
addPropertyChangeHandler in interface HasPropertyChangeHandlers
Parameters:
property - The name of the property or a property chain (e.g. customer.address.street) to receive events for. A property expression can end in a wildcard to indicate that changes of any property of the corresponding bean should be observed (e.g customer.address.*). A double wildcard can be used at the end of a property expression to register a cascading change handler for any nested property (e.g customer.**). Must not be null.
handler - The PropertyChangeHandler instance that should receive the events. Must not be null.

removePropertyChangeHandler

public void removePropertyChangeHandler(String property,
                                        PropertyChangeHandler<?> handler)
Description copied from interface: HasPropertyChangeHandlers
Removes a PropertyChangeHandler, previously registered by a call to HasPropertyChangeHandlers.addPropertyChangeHandler(String, PropertyChangeHandler) for the same property name. If the handler was added more than once to the same event source and property name, it will be notified one less time after being removed. If the provided handler is null, or was never added for the given property, no exception is thrown and no action is taken.

Specified by:
removePropertyChangeHandler in interface HasPropertyChangeHandlers
Parameters:
property - The name of the property or a property chain expression (e.g. customer.address.street). Must not be null.
handler - the PropertyChangeHandler instance

Errai 3.0.1-SNAPSHOT

Copyright © 2013-2014 JBoss, a division of Red Hat. All Rights Reserved.