Class AbstractValue<T>
- Type Parameters:
T- the value type
- All Implemented Interfaces:
Listeners.Superseding, Observable<T>, Observer<T>, Sensor, Value<T>
- Direct Known Subclasses:
AbstractComponentValue, PropertyValue
An abstract Value implementation handling everything except the value itself: supply
getValue() and setValue(Object) and the rest is inherited. This is the extension point -
implement Value from scratch and none of the machinery below is there.
get(), set(Object), clear() and update(java.util.function.UnaryOperator)
are final here, delegating to the package private base class that implements them. That is not ceremony: it
is what guarantees every value reaches the one ordering that makes the core tame - equality, then the lock,
then the validators, then the write, then the notification - since a subclass overriding set(Object)
could otherwise put a step of its own in front of any of them. The framework's own collection values, which
do need to widen that path, extend the base class directly instead.
The constructor parameter notify specifies whether this AbstractValue instance should call
notifyObserver() each time the value is set (Value.Notify.SET) or only when it changes
(Value.Notify.CHANGED), which is determined using Objects.deepEquals(Object, Object).
Implementations that want to handle notifications manually should use the
AbstractValue() or AbstractValue(Object) constructors.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classAbstractValue.AbstractBuilder<T, B extends Value.Builder<T,B>> An abstract base class for a value builderNested classes/interfaces inherited from interface Observer
Observer.Builder<T,B> Nested classes/interfaces inherited from interface Value
Value.Builder<T,B>, Value.BuilderFactory, Value.Locked, Value.Notify, Value.Validator<T> -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedCreates a nullableAbstractValueinstance, which does not notify listeners.protectedAbstractValue(@Nullable T nullValue) Creates anAbstractValueinstance, which does not notify listeners.protectedAbstractValue(@Nullable T nullValue, Value.Notify notify) Creates anAbstractValueinstance.protectedAbstractValue(AbstractValue.AbstractBuilder<T, ?> builder) Sets the builder's initial value, and applies its validators and links, from this constructor, sogetValue()andsetValue(Object)are called before the subclass's own constructor body runs.protectedAbstractValue(Value.Notify notify) Creates a nullableAbstractValueinstance. -
Method Summary
Modifier and TypeMethodDescriptionfinal booleanaddValidator(Value.Validator<? super T> validator) Adds a validator to thisValue.final ChangeObserver<T> changed()The default implementation returns a newChangeObserverinstance on each call, but subclasses are free to return the same instance.final voidclear()Clears this value, by setting it to null or the null value in case this is a non-null value.protected Observable<T> get()protected abstract TgetValue()Returns the actual internal valuefinal booleanIf false then get() is guaranteed to never return null.final 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.final voidCreates a bidirectional link between this and the given original value, so that changes in one are reflected in the other.final Value.Lockedlocked()Locking a value prevents it from being changed, it does not prevent it from being set.protected final voidNotifies the underlying observer that the underlying value has changed or at least that it may have changed, in caseshouldNotify(Object)allows it.final booleanremoveValidator(Value.Validator<? super T> validator) Removes the given validator from this valuefinal voidSets the value.protected abstract voidSets the actual internal valueprotected booleanshouldNotify(T value) Called bynotifyObserver()before the listeners and consumers are notified, with the value the consumers are to receive, the listeners and consumers only notified in case this method returns true.final voidunlink(Observable<T> observable) Unlinks this value from the given observablefinal voidUnlinks this value from the given original valuefinal voidupdate(UnaryOperator<@Nullable T> updateFunction) Updates the value with the result of applying the given function to the current value.final voidValidates the given value using all validators, asValue.set(Object)does, the null value standing in for null in case of a non-null value.Methods inherited from class AbstractObserver
addConsumer, addListener, addWeakConsumer, addWeakListener, notifyListeners, observer, removeConsumer, removeListener, removeWeakConsumer, removeWeakListener, sensor, when, whenMethods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface Observable
getOrThrow, getOrThrow, is, isNot, isNull, optionalMethods inherited from interface Observer
addConsumer, addWeakConsumer, observer, removeConsumer, removeWeakConsumer, sensor, when, whenMethods inherited from interface Sensor
addListener, addWeakListener, removeListener, removeWeakListener
-
Constructor Details
-
AbstractValue
protected AbstractValue()Creates a nullable
AbstractValueinstance, which does not notify listeners. -
AbstractValue
Creates a nullableAbstractValueinstance.- Parameters:
notify- specifies when to notify listeners
-
AbstractValue
Creates an
AbstractValueinstance, which does not notify listeners.If
nullValueis non-null, thisAbstractValueinstance will be non-nullable, meaningObservable.isNullable()returns false,get()is guaranteed to never return null and whenset(Object)receives null it is automatically translated tonullValue.- Parameters:
nullValue- the value to use instead of null
-
AbstractValue
Creates an
AbstractValueinstance.If
nullValueis non-null, thisAbstractValueinstance will be non-nullable, meaningObservable.isNullable()returns false,get()is guaranteed to never return null and whenset(Object)receives null it is automatically translated tonullValue.- Parameters:
nullValue- the value to use instead of nullnotify- specifies when to notify listeners
-
AbstractValue
Sets the builder's initial value, and applies its validators and links, from this constructor, so
getValue()andsetValue(Object)are called before the subclass's own constructor body runs. A field holding the value must therefore have no initializer, which would overwrite the value once this constructor returns, and neither method may rely on another field of the subclass, not yet assigned.- Parameters:
builder- the builder
-
-
Method Details
-
get
- Specified by:
getin interfaceObservable<T>- Returns:
- the value
-
set
Description copied from interface:ValueSets 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. -
clear
-
update
Description copied from interface:ValueUpdates 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
-
observable
- Specified by:
observablein interfaceValue<T>- Returns:
- a read-only
Observableinstance for this value
-
changed
Description copied from interface:ObservableThe default implementation returns a newChangeObserverinstance on each call, but subclasses are free to return the same instance.Note that when a new instance is returned per call, a listener added through one
changed()instance can only be removed through that same instance; retain it if the listener must later be removed.The instance subscribes to this observable only while it, its
ChangeObserver.previous()or itsChangeObserver.current()has listeners or consumers, so one never listened to costs nothing, and one whose listeners and consumers are all removed is left to be collected. One whose weak listeners and consumers have all been collected unsubscribes at the next change.The observer is notified when this observable notifies a value differing from the one before, by
Objects.deepEquals(Object, Object). An equal value, a refreshed instance for example, isn't reported, but replaces the one before as theChange.previous()of the next change.- Specified by:
changedin interfaceObservable<T>- Returns:
- a
ChangeObserverinstance notified when this observable has changed
-
locked
Description copied from interface:ValueLocking 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.
- Specified by:
lockedin interfaceValue<T>- Returns:
- the
Value.Lockedinstance controlling whether this value is locked
-
isNullable
public final boolean isNullable()Description copied from interface:ObservableIf false then get() is guaranteed to never return null.- Specified by:
isNullablein interfaceObservable<T>- Returns:
- true if this observable can be null
-
link
Description copied from interface:ValueCreates 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,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. -
unlink
-
link
Description copied from interface:ValueCreates 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. -
unlink
Description copied from interface:ValueUnlinks this value from the given observable -
addValidator
Description copied from interface:ValueAdds a validator to thisValue. Adding the same validator again has no effect.- Specified by:
addValidatorin interfaceValue<T>- Parameters:
validator- the validator- Returns:
- true if this value did not already contain the specified validator
-
removeValidator
Description copied from interface:ValueRemoves the given validator from this value- Specified by:
removeValidatorin interfaceValue<T>- Parameters:
validator- the validator- Returns:
- true if this value contained the specified validator
-
validate
Description copied from interface:ValueValidates the given value using all validators, asValue.set(Object)does, the null value standing in for null in case of a non-null value. -
getValue
-
setValue
Sets the actual internal value- Parameters:
value- the value
-
notifyObserver
protected final void notifyObserver()Notifies the underlying observer that the underlying value has changed or at least that it may have changed, in caseshouldNotify(Object)allows it. -
shouldNotify
Called bynotifyObserver()before the listeners and consumers are notified, with the value the consumers are to receive, the listeners and consumers only notified in case this method returns true. Allows a value whose state changes outsideValue.set(Object), held by a component for example, to validate a change before it is notified.Returns true by default.
- Parameters:
value- the value the consumers are to receive- Returns:
- true if the listeners and consumers should be notified
-
createObservable
- Returns:
- a new
Observableinstance representing this value
-