Package com.vaadin.flow.signals.shared

Class SharedValueSignal<T extends @Nullable Object>

java.lang.Object
com.vaadin.flow.signals.shared.AbstractSignal<T>
com.vaadin.flow.signals.shared.SharedValueSignal<T>
Type Parameters:
T - the signal value type
All Implemented Interfaces:
Signal<T>, Serializable
Direct Known Subclasses:
SharedNumberSignal
public class SharedValueSignal<T extends @Nullable Object> extends AbstractSignal<T>
A signal containing a value. The value is updated as a single atomic change. It's recommended to use immutable values and this is partially enforced by the way a new instance is created from the underlying JSON data every time the value is read.
See Also:

  • Constructor Details

    • SharedValueSignal

      public SharedValueSignal(T initialValue)
      Creates a new value signal with the given initial value. The type of the signal will be based on the type (Object.getClass()) of the initial value instance. The signal does not support clustering.
      Parameters:
      initialValue - the initial value to use, not null

    • SharedValueSignal

      public SharedValueSignal(Class<T> valueType)
      Creates a new value signal of the given type with no value. The signal does not support clustering.
      Parameters:
      valueType - the value type, not null

    • SharedValueSignal

      protected SharedValueSignal(SignalTree tree, Id id, CommandValidator validator, Class<T> valueType)
      Creates a new value signal instance with the given id and validator for the given signal tree with the given value type.
      Parameters:
      tree - the signal tree that contains the value for this signal, not null
      id - the id of the signal node within the signal tree, not null
      validator - the validator to check operations submitted to this singal, not null
      valueType - the value type, not null

  • Method Details

    • set

      public SignalOperation<T> set(T value)
      Sets the value of this signal.

      The result of the returned operation will be resolved with the previous value at the time when this operation was confirmed.

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

      Parameters:
      value - the value to set
      Returns:
      an operation containing the eventual result

    • extractValue

      protected @Nullable T extractValue(@Nullable Node.Data data)
      Description copied from class: AbstractSignal
      Extracts the value for this signal from the given signal data node.
      Specified by:
      extractValue in class AbstractSignal<T extends @Nullable Object>
      Parameters:
      data - the data node to extract the value from, or null if the node doesn't exist in the tree
      Returns:
      the signal value

    • usageChangeValue

      protected @Nullable Object usageChangeValue(Node.Data data)
      Description copied from class: AbstractSignal
      Gets a reference value that will be used to determine whether a dependency based on previous usage should be invalidated. This is done by getting one reference value when the dependency occurs and then comparing that to the current value to determine if the value has changed.

      The implementation should return an object that changes if and only if the AbstractSignal.get() of this signal changes.

      Specified by:
      usageChangeValue in class AbstractSignal<T extends @Nullable Object>
      Parameters:
      data - the data node to read from, not null
      Returns:
      a reference value to use for validity checks, may be null

    • replace

      public SignalOperation<Void> replace(T expectedValue, 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.
      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. If the original value has changed by the time this change is confirmed, then the returned value is ignored and the callback is run again with the new value as input. This process is repeated until canceled or until the update succeeds without conflicting changes.

      The process can be canceled through the returned operation instance. Note that canceling will only prevent further retries but the change will still be made if the currently running attempt succeeds.

      The result of the returned operation will be resolved with the previous value at the time when a successful update operation was confirmed.

      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 eventual result

    • verifyValue

      public SignalOperation<Void> verifyValue(T expectedValue)
      Checks that this signal has the expected value. This operation is only meaningful to use as a condition in a transaction. 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.
      Parameters:
      expectedValue - the expected value
      Returns:
      an operation containing the eventual result

    • withValidator

      public SharedValueSignal<T> withValidator(CommandValidator validator)
      Wraps this signal with a validator. The validator is used to check all value changing commands issued through the new signal instance. If this signal has a validator, then the new signal will use both validators. Note that due to the way validators are retained by asNode(), there's a possibility that the validator also receives commands that cannot be directly issued for a value signal.

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

      Parameters:
      validator - the validator to use, not null
      Returns:
      a new value signal that uses the validator, not null

    • asReadonly

      public SharedValueSignal<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

    • asNode

      public SharedNodeSignal asNode()
      Description copied from class: AbstractSignal
      Converts this signal into a node signal. This allows further conversion into any specific signal type through the methods in SharedNodeSignal. The converted signal is backed by the same underlying data and uses the same validator as this signal.
      Overrides:
      asNode in class AbstractSignal<T extends @Nullable Object>
      Returns:
      this signal as a node signal, not null

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • 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);
     }
 }

 SharedValueSignal<Person> personSignal = new SharedValueSignal<>(
         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