Package com.vaadin.flow.signals.local

Class ValueSignal<T>

java.lang.Object
com.vaadin.flow.signals.local.AbstractLocalSignal<T>
com.vaadin.flow.signals.local.ValueSignal<T>
Type Parameters:
T - the signal value type
All Implemented Interfaces:
Signal<T>, Serializable
public class ValueSignal<T> extends AbstractLocalSignal<T>
A local writable signal that holds a reference to an object.

Local signals are non-serializable and intended for UI-local state only. They do not participate in clustering and are simpler than shared signals.

Changing the signal to reference another immutable value is an atomic operation. It is safe to concurrently read and write the signal value from multiple threads.

The signal can also be used with mutable values in which case no thread safety is provided. Mutations must be done through modify(ValueModifier) to ensure dependents are informed after the modification is applied.

Local value signals can't be used inside signal transactions.

All operation objects returned from methods on this class are resolved immediately.

See Also:

  • Constructor Details

    • ValueSignal

      public ValueSignal(@Nullable T initialValue)
      Creates a new value signal with the given initial value.
      Parameters:
      initialValue - the initial value, may be null

    • ValueSignal

      public ValueSignal()
      Creates a new value signal with an initial value of null.

  • Method Details

    • checkPreconditions

      protected void checkPreconditions()
      Description copied from class: AbstractLocalSignal
      Hook for subclasses to perform precondition checks before accessing the value. Called while holding the lock. Default implementation does nothing.
      Overrides:
      checkPreconditions in class AbstractLocalSignal<T>

    • set

      public void set(@Nullable T value)
      Sets the value of this signal.

      Setting a new value will trigger effect functions that have reads from this signal.

      Parameters:
      value - the value to set

    • replace

      public SignalOperation<Void> replace(@Nullable T expectedValue, @Nullable T newValue)
      Sets the value of this signal if and only if the signal has the expected value at the time when the operation is confirmed. This is the signal counterpart to AtomicReference.compareAndSet(Object, Object). The result of the returned operation will be resolved as successful if the expected value was present and resolved as unsuccessful if any other value was present when the operation is processed.

      Comparison between the expected value and the new value is performed using Object.equals(Object).

      Parameters:
      expectedValue - the expected value
      newValue - the new value
      Returns:
      an operation containing the eventual result

    • update

      public CancelableOperation<T> update(SignalUpdater<T> updater)
      Updates the signal value based on the given callback. The callback receives the current signal value and returns the new value to use. This implementation acquires a lock while running the updater which means that it's never necessary to run the callback again. This also means that canceling the returned operation will never have any effect.

      The result of the returned operation is resolved with the same value that was passed to the updater callback.

      Update operations cannot participate in transactions since any retry would occur after the original transaction has already been committed. For this reason, the whole operation completely bypasses all transaction handling.

      Parameters:
      updater - the value update callback, not null
      Returns:
      an operation containing the result

    • modify

      public void modify(ValueModifier<T> modifier)
      Runs the given callback to apply changes to a mutable referenced value and then notifies dependents.

      This method is only intended for cases where concurrency is limited through other means, such as Vaadin's session lock. Using this method concurrently with any other methods on the same instance may, but is not guaranteed to, cause an ConcurrentModificationException. The exception can be thrown either from this method or from the other invoked method. This can happen even if the other method is safe for concurrent use.

      Parameters:
      modifier - a callback that receives the current value to modify, not null

    • asReadonly

      public Signal<T> asReadonly()
      Wraps this signal to not accept changes.

      This signal will keep its current configuration and changes applied through this instance will be visible through the wrapped instance.

      Returns:
      the new readonly signal, not null

    • updater

      public <C> SerializableConsumer<C> updater(ValueMerger<T,C> merger)
      Creates a callback that updates this signal value using the provided merger function. This is useful for creating write callbacks for bindValue when working with immutable value patterns.

      The merger function receives the current signal value and a new child value, and should return a new signal value. This is typically a method reference to a "with" style method on an immutable record or class.

      Example usage with an immutable record: 

       record Person(String name, int age) {
     Person withName(String name) {
         return new Person(name, this.age);
     }
 }

 ValueSignal<Person> personSignal = new ValueSignal<>(
         new Person("Alice", 30));
 textField.bindValue(personSignal.map(Person::name),
         personSignal.updater(Person::withName));
      Type Parameters:
      C - the child value type that will be provided to the callback
      Parameters:
      merger - the function to create a new signal value from the old value and a new child value, not null
      Returns:
      a callback that updates this signal using the merger function, not null

    • modifier

      public <C> SerializableConsumer<C> modifier(SignalModifier<T,C> modifier)
      Creates a callback that modifies this signal's mutable value in place using the provided modifier function. This is useful for creating write callbacks for bindValue when working with mutable value patterns.

      The modifier function receives the current signal value and a new child value, and should modify the signal value in place. This is typically a method reference to a setter method on a mutable bean.

      Example usage with a mutable bean: 

       class Person {
     private String name;
     private int age;

     public String getName() {
         return name;
     }

     public void setName(String name) {
         this.name = name;
     }
 }

 ValueSignal<Person> personSignal = new ValueSignal<>(new Person());
 textField.bindValue(personSignal.map(Person::getName),
         personSignal.modifier(Person::setName));
      Type Parameters:
      C - the child value type that will be provided to the callback
      Parameters:
      modifier - the function to modify the signal value in place with a new child value, not null
      Returns:
      a callback that modifies this signal using the modifier function, not null