Eclipse Platform
Release 3.3

org.eclipse.core.databinding
Class UpdateValueStrategy

java.lang.Object
  extended byorg.eclipse.core.databinding.UpdateStrategy
      extended byorg.eclipse.core.databinding.UpdateValueStrategy

public class UpdateValueStrategy
extends org.eclipse.core.databinding.UpdateStrategy

Customizes a Binding between two observable values. The following behaviors can be customized via the strategy:

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:
DataBindingContext.bindValue(IObservableValue, IObservableValue, UpdateValueStrategy, UpdateValueStrategy), Binding.getValidationStatus(), IValidator, IConverter

Nested Class Summary
protected static class UpdateStrategy.DefaultConverter
           
 
Field Summary
protected  IValidator afterConvertValidator
           
protected  IValidator afterGetValidator
           
protected  IValidator beforeSetValidator
           
protected  IConverter converter
           
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.
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.
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.
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 automaticlly on every change of the source observable value.
protected  boolean provideDefaults
           
 
Constructor Summary
UpdateValueStrategy()
          Creates a new update value strategy for automatically updating the destination observable value whenever the source observable value changes.
UpdateValueStrategy(boolean provideDefaults, int updatePolicy)
          Creates a new update value strategy with a configurable update policy.
UpdateValueStrategy(int updatePolicy)
          Creates a new update value strategy with a configurable update policy.
 
Method Summary
protected  void checkAssignable(Object toType, Object fromType, String errorString)
           
 Object convert(Object value)
          Converts the value from the source type to the destination type.
protected  IConverter createConverter(Object fromType, Object toType)
          Tries to create a converter that can convert from values of type fromType.
protected  IValidator createValidator(Object fromType, Object toType)
          Tries to create a validator that can validate values of type fromType.
protected  IStatus doSet(IObservableValue observableValue, Object value)
          Sets the current value of the given observable to the given value.
protected  void fillDefaults(IObservableValue source, IObservableValue destination)
          Fills out default values based upon the provided source and destination.
 int getUpdatePolicy()
           
protected  Boolean isAssignableFromTo(Object fromType, Object toType)
           
 UpdateValueStrategy setAfterConvertValidator(IValidator validator)
          Sets the validator to be invoked after the source value is converted to the type of the destination observable.
 UpdateValueStrategy setAfterGetValidator(IValidator validator)
          Sets the validator to be invoked after the source value is retrieved at the beginning of the synchronization process.
 UpdateValueStrategy setBeforeSetValidator(IValidator validator)
          Sets the validator to be invoked before the value is to be set on the destination at the end of the synchronization process.
 UpdateValueStrategy setConverter(IConverter converter)
          Sets the converter to be invoked when converting from the source type to the destination type.
 IStatus validateAfterConvert(Object value)
          Validates the value after it is converted.
 IStatus validateAfterGet(Object value)
          Validates the value after it is retrieved from the source.
 IStatus validateBeforeSet(Object value)
          Validates the value before it is set on the destination.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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 automaticlly on every change of the source observable value.


afterGetValidator

protected IValidator afterGetValidator

afterConvertValidator

protected IValidator afterConvertValidator

beforeSetValidator

protected IValidator beforeSetValidator

converter

protected IConverter converter

provideDefaults

protected boolean provideDefaults
Constructor Detail

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. 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.
updatePolicy - one of POLICY_NEVER, POLICY_ON_REQUEST, POLICY_CONVERT, or POLICY_UPDATE
Method Detail

convert

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

Default implementation will use the converter if one exists. If no converter exists no conversion occurs.

Parameters:
value -
Returns:
the converted value

createValidator

protected IValidator 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 -
toType -
Returns:
an IValidator, or null if unsuccessful

fillDefaults

protected void fillDefaults(IObservableValue source,
                            IObservableValue 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 -
destination -

getUpdatePolicy

public int getUpdatePolicy()
Returns:
the update policy

setAfterConvertValidator

public UpdateValueStrategy setAfterConvertValidator(IValidator validator)
Sets the validator to be invoked after the source value is converted to the type of the destination observable.

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

setAfterGetValidator

public UpdateValueStrategy setAfterGetValidator(IValidator validator)
Sets the validator to be invoked after the source value is retrieved at the beginning of the synchronization process.

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

setBeforeSetValidator

public UpdateValueStrategy setBeforeSetValidator(IValidator 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 -
Returns:
the receiver, to enable method call chaining

setConverter

public UpdateValueStrategy setConverter(IConverter converter)
Sets the converter to be invoked when converting from the source type to the destination type.

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

validateAfterConvert

public IStatus validateAfterConvert(Object 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 -
Returns:
an ok status

validateAfterGet

public IStatus validateAfterGet(Object 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 -
Returns:
an ok status

validateBeforeSet

public IStatus validateBeforeSet(Object 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 -
Returns:
an ok status

doSet

protected IStatus doSet(IObservableValue observableValue,
                        Object value)
Sets the current value of the given observable to the given value. Clients may extend but must call the super implementation.

Parameters:
observableValue -
value -
Returns:
status

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 -
toType -
Returns:
an IConverter, or null if unsuccessful

isAssignableFromTo

protected Boolean isAssignableFromTo(Object fromType,
                                     Object toType)
Parameters:
fromType -
toType -
Returns:
whether fromType is assignable to toType

Eclipse Platform
Release 3.3

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2007. All rights reserved.