Package org.eclipse.core.databinding

Class UpdateValueStrategy<S,D>

java.lang.Object
org.eclipse.core.databinding.UpdateValueStrategy<S,D>
Type Parameters:
S - the type of the value on the source side (i.e. the model side if this is a model-to-target update and the target side if this is a target-to-model update)
D - the type of the value on the destination side (i.e. the target side if this is a model-to-target update and the model side if this is a target-to-model update)
public class UpdateValueStrategy<S,D> extends Object
Customizes a Binding between two observable values. The following behaviors can be customized via the strategy:
  • Validation
  • Conversion
  • Automatic processing

The update phases are:

  1. Validate after get - validateAfterGet(Object)
  2. Conversion - convert(Object)
  3. Validate after conversion - validateAfterConvert(Object)
  4. Validate before set - validateBeforeSet(Object)
  5. Value set - doSet(IObservableValue, Object)

Validation:
Validators validate the value at multiple phases in the update process. Statuses returned from validators are aggregated into a MultiStatus until a status of ERROR or CANCEL is encountered. Either of these statuses will abort the update process. These statuses are available as the binding validation status.

Conversion:
A converter will convert the value from the type of the source observable into the type of the destination. The strategy has the ability to default converters for common scenarios.

Automatic processing:
The processing to perform when the source observable changes. This behavior is configured via policies provided on construction of the strategy (e.g. POLICY_NEVER, POLICY_CONVERT, POLICY_ON_REQUEST, POLICY_UPDATE).

Since:
1.0
See Also:

  • Field Details

    • POLICY_NEVER

      public static int POLICY_NEVER
      Policy constant denoting that the source observable's state should not be tracked and that the destination observable's value should never be updated.

    • POLICY_ON_REQUEST

      public static int POLICY_ON_REQUEST
      Policy constant denoting that the source observable's state should not be tracked, but that validation, conversion and updating the destination observable's value should be performed when explicitly requested.

    • POLICY_CONVERT

      public static int POLICY_CONVERT
      Policy constant denoting that the source observable's state should be tracked, including validating changes except for validateBeforeSet(Object), but that the destination observable's value should only be updated on request.

    • POLICY_UPDATE

      public static int POLICY_UPDATE
      Policy constant denoting that the source observable's state should be tracked, and that validation, conversion and updating the destination observable's value should be performed automatically on every change of the source observable value.

    • afterGetValidator

      protected IValidator<? super S> afterGetValidator

    • afterConvertValidator

      protected IValidator<? super D> afterConvertValidator

    • beforeSetValidator

      protected IValidator<? super D> beforeSetValidator

    • provideDefaults

      protected boolean provideDefaults

    • converter

      protected IConverter<? super S,? extends D> converter

  • Constructor Details

    • UpdateValueStrategy

      public UpdateValueStrategy()
      Creates a new update value strategy for automatically updating the destination observable value whenever the source observable value changes. Default validators and a default converter will be provided. The defaults can be changed by calling one of the setter methods.

    • UpdateValueStrategy

      public UpdateValueStrategy(int updatePolicy)
      Creates a new update value strategy with a configurable update policy. Default validators and a default converter will be provided. The defaults can be changed by calling one of the setter methods.
      Parameters:
      updatePolicy - one of POLICY_NEVER, POLICY_ON_REQUEST, POLICY_CONVERT, or POLICY_UPDATE

    • UpdateValueStrategy

      public UpdateValueStrategy(boolean provideDefaults, int updatePolicy)
      Creates a new update value strategy with a configurable update policy. Default validators and a default converter will be provided if provideDefaults is true, see DataBindingContext The defaults can be changed by calling one of the setter methods.
      Parameters:
      provideDefaults - if true, default validators and a default converter will be provided based on the observable value's type, see DataBindingContext
      updatePolicy - one of POLICY_NEVER, POLICY_ON_REQUEST, POLICY_CONVERT, or POLICY_UPDATE

  • Method Details

    • createValidator

      protected IValidator<S> createValidator(Object fromType, Object toType)
      Tries to create a validator that can validate values of type fromType. Returns null if no validator could be created. Either toType or modelDescription can be null, but not both.
      Parameters:
      fromType - the source type to validate
      toType - the desired target type
      Returns:
      an IValidator, or null if unsuccessful

    • fillDefaults

      protected void fillDefaults(IObservableValue<? extends S> source, IObservableValue<? super D> destination)
      Fills out default values based upon the provided source and destination. If the strategy is to default values it will attempt to default a converter. If the converter can be defaulted an attempt is made to default the after get validator. If a validator cannot be defaulted it will be null.
      Parameters:
      source - source observable, to be used for its type
      destination - destination observable, to be used for its type

    • getUpdatePolicy

      public int getUpdatePolicy()
      Returns:
      the update policy

    • setAfterConvertValidator

      public UpdateValueStrategy<S,D> setAfterConvertValidator(IValidator<? super D> validator)
      Sets the validator to be invoked after the source value is converted to the type of the destination observable.
      Parameters:
      validator - the new validator
      Returns:
      the receiver, to enable method call chaining

    • setAfterGetValidator

      public UpdateValueStrategy<S,D> setAfterGetValidator(IValidator<? super S> validator)
      Sets the validator to be invoked after the source value is retrieved at the beginning of the synchronization process.
      Parameters:
      validator - the new validator
      Returns:
      the receiver, to enable method call chaining

    • setBeforeSetValidator

      public UpdateValueStrategy<S,D> setBeforeSetValidator(IValidator<? super D> validator)
      Sets the validator to be invoked before the value is to be set on the destination at the end of the synchronization process.
      Parameters:
      validator - the new validator
      Returns:
      the receiver, to enable method call chaining

    • setConverter

      public UpdateValueStrategy<S,D> setConverter(IConverter<? super S,? extends D> converter)
      Sets the converter to be invoked when converting from the source type to the destination type.

      If the converter throws any exceptions they are reported as validation errors, using the exception message.

      Parameters:
      converter - the new converter
      Returns:
      the receiver, to enable method call chaining

    • validateAfterConvert

      public IStatus validateAfterConvert(D value)
      Validates the value after it is converted.

      Default implementation will use the validator if one exists. If one does not exist no validation will occur.

      Parameters:
      value - value to validate
      Returns:
      validation status

    • validateAfterGet

      public IStatus validateAfterGet(S value)
      Validates the value after it is retrieved from the source.

      Default implementation will use the validator if one exists. If one does not exist no validation will occur.

      Parameters:
      value - value to validate
      Returns:
      validation status

    • validateBeforeSet

      public IStatus validateBeforeSet(D value)
      Validates the value before it is set on the destination.

      Default implementation will use the validator if one exists. If one does not exist no validation will occur.

      Parameters:
      value - value to validate
      Returns:
      validation status

    • doSet

      protected IStatus doSet(IObservableValue<? super D> observableValue, D value)
      Sets the current value of the given observable to the given value. Clients may extend but must call the super implementation.
      Parameters:
      observableValue - observable to change
      value - new value to set
      Returns:
      status

    • create

      public static <S, D> UpdateValueStrategy<S,D> create(IConverter<S,D> converter)
      Convenience method that creates an UpdateValueStrategy with the given converter. It uses POLICY_UPDATE.
      Parameters:
      converter - the converter
      Returns:
      the update strategy
      Since:
      1.6

    • never

      public static <S, D> UpdateValueStrategy<S,D> never()
      Convenience method that creates an update strategy that never updates its observables, using POLICY_NEVER and no defaults.
      Returns:
      the update strategy
      Since:
      1.8

    • checkAssignable

      protected final void checkAssignable(Object toType, Object fromType, String errorString)

    • createConverter

      protected IConverter<?,?> createConverter(Object fromType, Object toType)
      Tries to create a converter that can convert from values of type fromType. Returns null if no converter could be created. Either toType or modelDescription can be null, but not both.
      Parameters:
      fromType - source type
      toType - target type
      Returns:
      an IConverter, or null if unsuccessful

    • isAssignableFromTo

      protected Boolean isAssignableFromTo(Object fromType, Object toType)
      Returns Boolean.TRUE if the from type is assignable to the to type, or Boolean.FALSE if it not, or null if unknown.
      Parameters:
      fromType - source type to assign
      toType - target type to check assignability against
      Returns:
      whether fromType is assignable to toType, or null if unknown

    • logErrorWhileSettingValue

      protected IStatus logErrorWhileSettingValue(Exception ex)
      Parameters:
      ex - the exception, that was caught
      Returns:
      the validation status

    • convert

      public D convert(S value)
      Converts the value from the source type to the destination type.

      Default implementation will use the setConverter(IConverter), if one exists. If no converter exists no conversion occurs.

      Parameters:
      value - source value to convert
      Returns:
      the converted value