Interface Value<T>
- Type Parameters:
T- the type of the wrapped value
- All Superinterfaces:
Observable<T>, Observer<T>, Sensor
- All Known Subinterfaces:
ComponentValue<C,T>, EntityConditions.ConditionValue, EntityEditor.EditorValue<T>, FilterModel.IncludePredicate<T>, ImagePane.ImageValue, MultiSelection.Indexes, MultiSelection.Items<R>, ValueCollection<T, C>, ValueList<T>, ValueSet<T>
- All Known Implementing Classes:
AbstractComponentValue, AbstractTextComponentValue, AbstractValue, PropertyValue
An observable wrapper for a value.
Nullable integer based Value:
Value<Integer> value = Value.nullable();
value.set(42);
value.addConsumer(this::onValueChange);
value.isNullable(); // true
Non-null boolean based Value, using 'false' as a null substitute:
Value<Boolean> value = Value.nonNull(false);
value.set(true);
value.set(null);
value.get(); // false
value.isNullable(); // false
Non-null String based Value, using "none" as a null substitute:
Value<String> value = Value.builder()
.nonNull("none")
.value("hello") // the initial value
.notify(Notify.SET) // notifies listeners when set
.validator(this::validateString) // using a validator
.listener(this::onStringSet) // and a listener
.build();
value.isNullable(); // false
value.set("hey");
value.set(null); // reverts to the null substitute: "none"
A factory for Value instances.
The value is set before its listeners and consumers are notified, so an exception thrown by one propagates
from set(Object) with the value set, and ends the notification, those after it not notified. A link is one
of them, so a value linked after the one throwing keeps the value it had, until the next change.
Thread Safety: Listener management (add/remove) is thread-safe and supports concurrent access.
However, value modifications via set(Object) are NOT thread-safe and should be
performed from a single thread (such as an application UI thread). Subclasses may provide thread-safety.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceValue.Builder<T, B extends Value.Builder<T,B>> Builds aValueinstance.static interfaceProvidesValue.Builderinstances for nullable or non-nullable values.static interfaceControls whether aValueinstance is locked.static enumSpecifies when a Value instance notifies its listeners and consumers.static interfaceAValue.ValidatorforValues. -
Method Summary
Modifier and TypeMethodDescriptionbooleanaddValidator(Value.Validator<? super T> validator) Adds a validator to thisValue.static Value.BuilderFactorybuilder()voidclear()Clears this value, by setting it to null or the null value in case this is a non-null value.voidlink(Observable<T> observable) Creates a unidirectional link between this value and the given observable, so that changes in the observable are reflected in this one.voidCreates a bidirectional link between this and the given original value, so that changes in one are reflected in the other.locked()Locking a value prevents it from being changed, it does not prevent it from being set.static <T> Value<T> nonNull(T nullValue) Creates a new non-nullValueinstance, using the given value as a null-substitute, usingValue.Notify.CHANGED.static <T> Value<T> nullable()Creates a new nullableValueinstance, wrapping a null initial value, usingValue.Notify.CHANGED.static <T> Value<T> Creates a new nullableValueinstance, wrapping the given initial value, usingValue.Notify.CHANGED.booleanremoveValidator(Value.Validator<? super T> validator) Removes the given validator from this valuevoidSets the value.voidunlink(Observable<T> observable) Unlinks this value from the given observablevoidUnlinks this value from the given original valuedefault voidupdate(UnaryOperator<@Nullable T> updateFunction) Updates the value with the result of applying the given function to the current value.voidValidates the given value using all validators, asset(Object)does, the null value standing in for null in case of a non-null value.Methods inherited from interface Observable
changed, get, getOrThrow, getOrThrow, is, isNot, isNull, isNullable, optionalMethods inherited from interface Observer
addConsumer, addWeakConsumer, observer, removeConsumer, removeWeakConsumer, sensor, when, whenMethods inherited from interface Sensor
addListener, addWeakListener, removeListener, removeWeakListener
-
Method Details
-
set
Sets the value. Note that change listener notifications depend on theValue.Notifypolicy associated with this value.A listener or consumer setting the value again, trimming, clamping or reverting a change, starts a nested notification of the new value, which supersedes the one in progress: once it has run, the notification of the value it replaced ends, so the listeners and consumers after the one setting it hear the new value alone, and those before it both, in order. To notify the value once, normalize it in
BaseValue.setValue(Object)instead, or reject it with aValue.Validator.- Parameters:
value- the value- Throws:
IllegalArgumentException- in case the given value is invalidIllegalStateException- in case this value islockedand the given value differs from the current one- See Also:
-
clear
void clear()Clears this value, by setting it to null or the null value in case this is a non-null value. -
update
Updates the value with the result of applying the given function to the current value.Value<Integer> value = Value.nonNull(0); // increment the value by one value.update(currentValue -> currentValue + 1);- Parameters:
updateFunction- a function mapping from the current value to the new value- Throws:
NullPointerException- in caseupdateFunctionis null
-
observable
Observable<T> observable()- Returns:
- a read-only
Observableinstance for this value
-
locked
Value.Locked locked()Locking a value prevents it from being changed, it does not prevent it from being set.
Note that locking a value does not prevent linked values from being changed.
A locked value in a linked value chain, may cause it to go out of sync, since any subsequent linked values will not be updated after a locked value is encountered.
- Returns:
- the
Value.Lockedinstance controlling whether this value is locked
-
link
Creates a bidirectional link between this and the given original value, so that changes in one are reflected in the other.
Note that after a call to this method this value is the same as
originalValue.The two behave as one logical value: either end validates against both ends' validators, before either is written, so the pair can not come to hold a value one end rejects. This holds for any
Value,validate(Object)being the gate.Each end updates the other from a listener, notified in turn with the others, so the pair can diverge where that update does not happen: a listener added before it throwing, which ends the notification, or the other end
locked. A non-null value linked to a nullable one holding null holds its null value in its place.Cycle detection reaches as far as the framework's own link bookkeeping, which means every value extending
AbstractValue. AValueimplemented from scratch keeps its own links, if it has any, so a cycle running through one is not detected - the reciprocal update guard still keeps a single link from cycling back on itself.- Parameters:
originalValue- the original value to link this value to- Throws:
IllegalStateException- in case the values are already linked or if a cycle is detectedIllegalArgumentException- in case the original value is not valid according to this value's validators
-
unlink
Unlinks this value from the given original value- Parameters:
originalValue- the original value to unlink from this one- Throws:
IllegalStateException- in case the values are not linked
-
link
Creates a unidirectional link between this value and the given observable, so that changes in the observable are reflected in this one. Note that after a call to this method the value of this value is the same as the observable.- Parameters:
observable- the observable to link this value to- Throws:
IllegalArgumentException- in case the observable is not valid according to this value's validators
-
unlink
Unlinks this value from the given observable- Parameters:
observable- the observable to unlink
-
addValidator
Adds a validator to thisValue. Adding the same validator again has no effect.- Parameters:
validator- the validator- Returns:
- true if this value did not already contain the specified validator
- Throws:
IllegalArgumentException- in case the current value is invalid according to the validator
-
removeValidator
Removes the given validator from this value- Parameters:
validator- the validator- Returns:
- true if this value contained the specified validator
-
validate
Validates the given value using all validators, asset(Object)does, the null value standing in for null in case of a non-null value.- Parameters:
value- the value to validate- Throws:
IllegalArgumentException- in case the given value is invalid according to a validator
-
nullable
Creates a new nullableValueinstance, wrapping a null initial value, usingValue.Notify.CHANGED.- Type Parameters:
T- the value type- Returns:
- a nullable Value
-
nullable
Creates a new nullableValueinstance, wrapping the given initial value, usingValue.Notify.CHANGED.- Type Parameters:
T- the value type- Parameters:
value- the initial value- Returns:
- a nullable Value
-
nonNull
Creates a new non-nullValueinstance, using the given value as a null-substitute, usingValue.Notify.CHANGED.- Type Parameters:
T- the value type- Parameters:
nullValue- the null value substitute- Returns:
- a non-null Value
-
builder
- Returns:
- a new
Value.BuilderFactoryinstance
-