Module is.codion.common.core
Package is.codion.common.value

Interface Value<T>

Type Parameters:
T - the type of the wrapped value
All Superinterfaces:
Observable<T>, Observer<T>
All Known Subinterfaces:
ComponentValue<C,T>, EntityEditModel.EditorValue<T>, EntityQueryModel.AdditionalCondition, FilterModel.IncludedPredicate<T>, 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.

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.
      Parameters:
      value - the value
      Throws:
      IllegalArgumentException - in case the given value is invalid
      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.

    • map

      default void map(UnaryOperator<@Nullable T> mapper)
      Sets a new value mapped from the current value. 
       Value<Integer> value = Value.value(0);

 // increment the value by one
 value.map(currentValue -> currentValue + 1);
      Parameters:
      mapper - maps from the current value to a new value
      Throws:
      NullPointerException - in case mapper is null

    • observable

      Observable<T> observable()
      Returns:
      a read-only Observable instance for this value

    • 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.
      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 values 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 values 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)
      Validate the given value using all validators
      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