Package com.vaadin.flow.signals.shared

Class SharedMapSignal<T extends @Nullable Object>

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

  • Constructor Details

    • SharedMapSignal

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

    • SharedMapSignal

      protected SharedMapSignal(SignalTree tree, Id id, CommandValidator validator, Class<T> elementType)
      Creates a new map 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 Map<String,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 Map<String,SharedValueSignal<T extends @Nullable Object>>>
      Returns:
      the signal value

    • peek

      public Map<String,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 Map<String,SharedValueSignal<T extends @Nullable Object>>>
      Returns:
      the signal value

    • peekConfirmed

      public Map<String,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 Map<String,SharedValueSignal<T extends @Nullable Object>>>
      Returns:
      the confirmed signal value

    • extractValue

      protected Map<String,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 Map<String,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 Map<String,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

    • put

      public SignalOperation<T> put(String key, T value)
      Associates the given value with the given key. If an entry already exists for the given key, then that entry is updated. If no entry exists, then a new entry is created.

      The result of the returned operation will be resolved with the previous value at the time when this operation was confirmed. The previous value is null if no entry existed or if it existed with a null value.

      Note that this operation does not give direct access to the child signal that was created or updated. Use putIfAbsent(String, Object) for that purpose.

      Parameters:
      key - the key to use, not null
      value - the value to set
      Returns:
      an operation containing the eventual result

    • putIfAbsent

      public SignalOperation<PutIfAbsentResult<SharedValueSignal<T>>> putIfAbsent(String key, T value)
      Creates a new entry with the given value if an entry with the given key doesn't already exist. If an entry exists, then the given value is ignored. The operation will be resolved as successful regardless of whether the key was already used. The result contains information about whether a new entry was created and a reference to the signal for the entry.
      Parameters:
      key - the key to use, not null
      value - the value to set
      Returns:
      an operation containing the eventual result with the entry signal

    • remove

      public SignalOperation<T> remove(String key)
      Removes the mapping for the given key. The operation will be resolved as successful if a mapping existed and as a failure if there was no mapping. In case of a successful operation, the result value will be the value associated with the key when the operation was processed.
      Parameters:
      key - the key to use, not null
      Returns:
      an operation containing the eventual result

    • clear

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

    • verifyKey

      public SignalOperation<Void> verifyKey(String key, AbstractSignal<?> expectedChild)
      Checks that the given child is mapped to the given key in this map. 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 mapped to the given key in this map when the operation is processed.
      Parameters:
      key - the key to check, not null
      expectedChild - the expected child signal, not null
      Returns:
      an operation containing the eventual result

    • verifyHasKey

      public SignalOperation<Void> verifyHasKey(String key)
      Checks that there is a mapping for the given key in this map. 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 key has a mapping in this map when the operation is processed.
      Parameters:
      key - the key to check, not null
      Returns:
      an operation containing the eventual result

    • verifyKeyAbsent

      public SignalOperation<Void> verifyKeyAbsent(String key)
      Checks that there is no mapping for the given key in this map. 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 key has no mapping in this map when the operation is processed.
      Parameters:
      key - the key to check, not null
      Returns:
      an operation containing the eventual result

    • withValidator

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

    • asReadonly

      public SharedMapSignal<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 map 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 Map<String,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