Package com.vaadin.flow.signals.shared

Class SharedListSignal<T extends @Nullable Object>

java.lang.Object
com.vaadin.flow.signals.shared.AbstractSignal<@NonNull List<SharedValueSignal<T>>>
com.vaadin.flow.signals.shared.SharedListSignal<T>
Type Parameters:
T - the element type
All Implemented Interfaces:
Signal<@NonNull List<SharedValueSignal<T>>>, Serializable
public class SharedListSignal<T extends @Nullable Object> extends AbstractSignal<@NonNull List<SharedValueSignal<T>>>
A signal containing a list of values. Supports atomic updates to the list structure. Each value in the list is accessed as a separate SharedValueSignal instance which enables atomic updates to the value of that list entry.
See Also:

  • Constructor Details

    • SharedListSignal

      public SharedListSignal(Class<T> elementType)
      Creates a new list signal with the given element type. The signal does not support clustering.
      Parameters:
      elementType - the element type, not null

    • SharedListSignal

      protected SharedListSignal(SignalTree tree, Id id, CommandValidator validator, Class<T> elementType)
      Creates a new list signal instance with the given id and validator for the given signal tree with the given element 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
      elementType - the element type, not null

  • Method Details

    • get

      public List<SharedValueSignal<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 AbstractSignal<@NonNull List<SharedValueSignal<T extends @Nullable Object>>>
      Returns:
      the signal value

    • peek

      public List<SharedValueSignal<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 AbstractSignal<@NonNull List<SharedValueSignal<T extends @Nullable Object>>>
      Returns:
      the signal value

    • peekConfirmed

      public List<SharedValueSignal<T>> peekConfirmed()
      Description copied from class: AbstractSignal
      Reads the confirmed value without setting up any dependencies. The confirmed value doesn't consider changes in the current transaction or changes that have been submitted but not yet confirmed in a cluster.
      Overrides:
      peekConfirmed in class AbstractSignal<@NonNull List<SharedValueSignal<T extends @Nullable Object>>>
      Returns:
      the confirmed signal value

    • extractValue

      protected List<SharedValueSignal<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<@NonNull List<SharedValueSignal<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 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<@NonNull List<SharedValueSignal<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

    • insertFirst

      public InsertOperation<SharedValueSignal<T>> insertFirst(T value)
      Inserts a value as the first entry in this list.
      Parameters:
      value - the value to insert
      Returns:
      an operation containing a signal for the inserted entry and the eventual result

    • insertLast

      public InsertOperation<SharedValueSignal<T>> insertLast(T value)
      Inserts a value as the last entry in this list.
      Parameters:
      value - the value to insert
      Returns:
      an operation containing a signal for the inserted entry and the eventual result

    • insertAt

      public InsertOperation<SharedValueSignal<T>> insertAt(T value, SharedListSignal.ListPosition at)
      Inserts a value at the given position in this list. The operation fails if the position is not valid at the time when the operation is processed.
      Parameters:
      value - the value to insert
      at - the insert position, not null
      Returns:
      an operation containing a signal for the inserted entry and the eventual result

    • moveTo

      public SignalOperation<Void> moveTo(AbstractSignal<T> child, SharedListSignal.ListPosition to)
      Moves the given child signal to the given position in this list. The operation fails if the child is not a child or if this list of if position is not valid at the time when the operation is processed.
      Parameters:
      child - the child signal to move, not null
      to - the position to move to, not null
      Returns:
      an operation containing the eventual result

    • remove

      public SignalOperation<Void> remove(SharedValueSignal<T> child)
      Removes the given child from this list. The operation fails if the child is not a child of this list at the time when the operation is processed.
      Parameters:
      child - the child to remove, not null
      Returns:
      an operation containing the eventual result

    • clear

      public SignalOperation<Void> clear()
      Removes all children from this list. Note that is this list shares data with a SharedNodeSignal that has map children, then the map children will also be removed.
      Overrides:
      clear in class AbstractSignal<@NonNull List<SharedValueSignal<T extends @Nullable Object>>>
      Returns:
      an operation containing the eventual result

    • verifyPosition

      public SignalOperation<Void> verifyPosition(AbstractSignal<?> child, SharedListSignal.ListPosition expectedPosition)
      Checks that the given child is at the given position in this list. 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 given child is a child of this list and at the given position when the operation is processed.
      Parameters:
      child - the child to test, not null
      expectedPosition - the expected position of the child, not null
      Returns:
      an operation containing the eventual result

    • verifyChild

      public SignalOperation<Void> verifyChild(AbstractSignal<?> child)
      Checks that the given signal is a child in this list. 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 given child is a child of this list and at the given position when the operation is processed.
      Parameters:
      child - the child to look for test, not null
      Returns:
      an operation containing the eventual result

    • withValidator

      public SharedListSignal<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 and all child signals. 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 list signal or its children.

      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 list signal that uses the validator, not null

    • asReadonly

      public SharedListSignal<T> asReadonly()
      Wraps this signal to not accept changes. Child value signals retrieved through the wrapped signal will also 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 list 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<@NonNull List<SharedValueSignal<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