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 aBinding
between twoobservable values
. The following behaviors can be customized via the strategy:- Validation
- Conversion
- Automatic processing
The update phases are:
- Validate after get -
validateAfterGet(Object)
- Conversion -
convert(Object)
- Validate after conversion -
validateAfterConvert(Object)
- Validate before set -
validateBeforeSet(Object)
- Value set -
doSet(IObservableValue, Object)
Validation:
Validators
validate the value at multiple phases in the update process. Statuses returned from validators are aggregated into aMultiStatus
until a status ofERROR
orCANCEL
is encountered. Either of these statuses will abort the update process. These statuses are available as thebinding validation status
.Conversion:
Aconverter
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
).
-
-
Field Summary
Fields Modifier and Type Field Description protected IValidator<? super D>
afterConvertValidator
protected IValidator<? super S>
afterGetValidator
protected IValidator<? super D>
beforeSetValidator
protected IConverter<? super S,? extends D>
converter
static int
POLICY_CONVERT
Policy constant denoting that the source observable's state should be tracked, including validating changes except forvalidateBeforeSet(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 automatically on every change of the source observable value.protected boolean
provideDefaults
-
Constructor Summary
Constructors Constructor Description 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
checkAssignable(Object toType, Object fromType, String errorString)
D
convert(S value)
Converts the value from the source type to the destination type.static <S,D>
UpdateValueStrategy<S,D>create(IConverter<S,D> converter)
Convenience method that creates anUpdateValueStrategy
with the given converter.protected IConverter<?,?>
createConverter(Object fromType, Object toType)
Tries to create a converter that can convert from values of type fromType.protected IValidator<S>
createValidator(Object fromType, Object toType)
Tries to create a validator that can validate values of type fromType.protected IStatus
doSet(IObservableValue<? super D> observableValue, D value)
Sets the current value of the given observable to the given value.protected void
fillDefaults(IObservableValue<? extends S> source, IObservableValue<? super D> destination)
Fills out default values based upon the providedsource
anddestination
.int
getUpdatePolicy()
protected Boolean
isAssignableFromTo(Object fromType, Object toType)
ReturnsBoolean.TRUE
if the from type is assignable to the to type, orBoolean.FALSE
if it not, ornull
if unknown.protected IStatus
logErrorWhileSettingValue(Exception ex)
static <S,D>
UpdateValueStrategy<S,D>never()
Convenience method that creates an update strategy that never updates its observables, usingPOLICY_NEVER
and no defaults.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.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.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.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.IStatus
validateAfterConvert(D value)
Validates the value after it is converted.IStatus
validateAfterGet(S value)
Validates the value after it is retrieved from the source.IStatus
validateBeforeSet(D value)
Validates the value before it is set on the destination.
-
-
-
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 forvalidateBeforeSet(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 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 ofPOLICY_NEVER
,POLICY_ON_REQUEST
,POLICY_CONVERT
, orPOLICY_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 ifprovideDefaults
istrue
, seeDataBindingContext
The defaults can be changed by calling one of the setter methods.- Parameters:
provideDefaults
- iftrue
, default validators and a default converter will be provided based on the observable value's type, seeDataBindingContext
updatePolicy
- one ofPOLICY_NEVER
,POLICY_ON_REQUEST
,POLICY_CONVERT
, orPOLICY_UPDATE
-
-
Method Detail
-
createValidator
protected IValidator<S> createValidator(Object fromType, Object toType)
Tries to create a validator that can validate values of type fromType. Returnsnull
if no validator could be created. Either toType or modelDescription can benull
, but not both.- Parameters:
fromType
- the source type to validatetoType
- 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 providedsource
anddestination
. 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 theafter get validator
. If a validator cannot be defaulted it will benull
.- Parameters:
source
- source observable, to be used for its typedestination
- 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 changevalue
- new value to set- Returns:
- status
-
create
public static <S,D> UpdateValueStrategy<S,D> create(IConverter<S,D> converter)
Convenience method that creates anUpdateValueStrategy
with the given converter. It usesPOLICY_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, usingPOLICY_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. Returnsnull
if no converter could be created. Either toType or modelDescription can benull
, but not both.- Parameters:
fromType
- source typetoType
- target type- Returns:
- an IConverter, or
null
if unsuccessful
-
isAssignableFromTo
protected Boolean isAssignableFromTo(Object fromType, Object toType)
ReturnsBoolean.TRUE
if the from type is assignable to the to type, orBoolean.FALSE
if it not, ornull
if unknown.- Parameters:
fromType
- source type to assigntoType
- 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
-
-