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

public interface Value<T> extends Observable<T>

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:
  • Method Details

    • set

      void set(@Nullable T value)
      Sets the value. Note that change listener notifications depend on the Value.Notify policy 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 a Value.Validator.

      Parameters:
      value - the value
      Throws:
      IllegalArgumentException - in case the given value is invalid
      IllegalStateException - in case this value is locked and 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

      default void update(UnaryOperator<@Nullable T> updateFunction)
      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 case updateFunction is null
    • observable

      Observable<T> observable()
      Returns:
      a read-only Observable instance 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.Locked instance controlling whether this value is locked
    • link

      void link(Value<T> originalValue)

      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. A Value implemented 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 detected
      IllegalArgumentException - in case the original value is not valid according to this value's validators
    • unlink

      void unlink(Value<T> originalValue)
      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

      void link(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. 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

      void unlink(Observable<T> observable)
      Unlinks this value from the given observable
      Parameters:
      observable - the observable to unlink
    • addValidator

      boolean addValidator(Value.Validator<? super T> validator)
      Adds a validator to this Value. 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

      boolean removeValidator(Value.Validator<? super T> validator)
      Removes the given validator from this value
      Parameters:
      validator - the validator
      Returns:
      true if this value contained the specified validator
    • validate

      void validate(@Nullable T value)
      Validates the given value using all validators, as set(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

      static <T> Value<T> nullable()
      Creates a new nullable Value instance, wrapping a null initial value, using Value.Notify.CHANGED.
      Type Parameters:
      T - the value type
      Returns:
      a nullable Value
    • nullable

      static <T> Value<T> nullable(@Nullable T value)
      Creates a new nullable Value instance, wrapping the given initial value, using Value.Notify.CHANGED.
      Type Parameters:
      T - the value type
      Parameters:
      value - the initial value
      Returns:
      a nullable Value
    • nonNull

      static <T> Value<T> nonNull(T nullValue)
      Creates a new non-null Value instance, using the given value as a null-substitute, using Value.Notify.CHANGED.
      Type Parameters:
      T - the value type
      Parameters:
      nullValue - the null value substitute
      Returns:
      a non-null Value
    • builder

      static Value.BuilderFactory builder()
      Returns:
      a new Value.BuilderFactory instance