Package com.vaadin.flow.signals.local

Class ListSignal<T extends @Nullable Object>

java.lang.Object
com.vaadin.flow.signals.local.AbstractLocalSignal<@NonNull List<ValueSignal<T>>>
com.vaadin.flow.signals.local.ListSignal<T>
Type Parameters:
T - the element type
All Implemented Interfaces:
Signal<@NonNull List<ValueSignal<T>>>, Serializable
public class ListSignal<T extends @Nullable Object> extends AbstractLocalSignal<@NonNull List<ValueSignal<T>>>
A local list signal that holds a list of writable signals, enabling per-entry reactivity.

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

Structural mutations (add, remove, clear) trigger list-level dependents. Entry-level mutations (updating an entry's value) only trigger that entry's dependents.

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

See Also:

  • Constructor Details

    • ListSignal

      public ListSignal()
      Creates a new empty list signal.

    • ListSignal

      public ListSignal(SerializableBiPredicate<T,T> equalityChecker)
      Creates a new empty list signal with a custom equality checker.

      The equality checker is used to determine if a new value is equal to the current value of an entry signal when that entry's value is updated via ValueSignal.set(Object). It does not apply when inserting new items into the list (e.g., via insertLast(Object)). If the equality checker returns true, the value update is skipped, and no change notification is triggered, i.e., no dependent effect function is triggered.

      The equality checker is applied to all ValueSignal instances created for entries in this list.

      Parameters:
      equalityChecker - the predicate used to compare entry values for equality, not null

  • Method Details

    • get

      public List<ValueSignal<T>> get()
      Description copied from interface: Signal
      Gets the current value of this signal. The value is read in a way that takes the current transaction into account and in the case of clustering also changes that have been submitted to the cluster but not yet confirmed.

      If the signal implementation supports transactions, then reading the value in a regular (i.e. Transaction.Type.STAGED) transaction makes the transaction depend on the value so that the transaction fails in case the signal value is changed concurrently.

      Reading the value inside an Signal.unboundEffect(EffectAction) or Signal.computed(SignalComputation) callback sets up that effect or computed signal to depend on the signal.

      This method must only be called within a reactive context such as an effect, a computed signal, an explicit Signal.untracked(ValueSupplier) block, or a transaction. Calling it outside such a context throws an IllegalStateException. Use Signal.peek() for one-time reads that do not need dependency tracking.

      Specified by:
      get in interface Signal<T extends @Nullable Object>
      Overrides:
      get in class AbstractLocalSignal<@NonNull List<ValueSignal<T extends @Nullable Object>>>
      Returns:
      the signal value

    • peek

      public List<ValueSignal<T>> peek()
      Description copied from interface: Signal
      Reads the value without setting up any dependencies. This method returns the same value as Signal.get() but without creating a dependency when used inside a transaction, effect or computed signal.

      Unlike Signal.get(), this method can be called outside a reactive context and is the recommended way to read a signal value for one-time use, such as logging, assertions, or initializing non-reactive UI.

      Specified by:
      peek in interface Signal<T extends @Nullable Object>
      Overrides:
      peek in class AbstractLocalSignal<@NonNull List<ValueSignal<T extends @Nullable Object>>>
      Returns:
      the signal value

    • 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. The base implementation verifies that the signal is not accessed from a different session than the one that first used it.
      Overrides:
      checkPreconditions in class AbstractLocalSignal<@NonNull List<ValueSignal<T extends @Nullable Object>>>

    • insertFirst

      public ValueSignal<T> insertFirst(T value)
      Inserts a value as the first entry in this list.
      Parameters:
      value - the value to insert
      Returns:
      a signal for the inserted entry

    • insertLast

      public ValueSignal<T> insertLast(T value)
      Inserts a value as the last entry in this list.
      Parameters:
      value - the value to insert
      Returns:
      a signal for the inserted entry

    • insertAt

      public ValueSignal<T> insertAt(int index, T value)
      Inserts a value at the given index in this list.

      Note: This method should only be used in non-concurrent cases where the list structure is not being modified by other threads. The index is sensitive to concurrent modifications and may lead to unexpected results if the list is modified between determining the index and calling this method. For concurrent cases, prefer using insertFirst(Object) or insertLast(Object).

      Parameters:
      index - the index at which to insert (0 for first, size() for last)
      value - the value to insert
      Returns:
      a signal for the inserted entry
      Throws:
      IndexOutOfBoundsException - if index is negative or greater than size()

    • remove

      public void remove(ValueSignal<T> entry)
      Removes the given entry from this list. Does nothing if the entry is not in the list.
      Parameters:
      entry - the entry to remove

    • moveTo

      public void moveTo(ValueSignal<T> entry, int toIndex)
      Moves an existing entry to a new position in this list. The same ValueSignal instance is preserved — no new signal is created.

      Does nothing if the entry is already at the target index.

      Note: This method should only be used in non-concurrent cases where the list structure is not being modified by other threads. The index is sensitive to concurrent modifications and may lead to unexpected results if the list is modified between determining the index and calling this method.

      Parameters:
      entry - the entry to move
      toIndex - the desired final index (0-based)
      Throws:
      IllegalArgumentException - if the entry is not in the list
      IndexOutOfBoundsException - if toIndex is negative or >= size

    • clear

      public void clear()
      Removes all entries from this list.

    • toString

      public String toString()
      Overrides:
      toString in class Object