Package com.vaadin.flow.signals

Interface Signal<T extends @Nullable Object>

Type Parameters:
T - the signal value type
All Superinterfaces:
Serializable
All Known Implementing Classes:
AbstractLocalSignal, AbstractSignal, ComputedSignal, ListSignal, SharedListSignal, SharedMapSignal, SharedNodeSignal, SharedNumberSignal, SharedValueSignal, ValueSignal
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface Signal<T extends @Nullable Object> extends Serializable
A signal is a reactive value holder with automatic subscription and unsubscription of listeners.

Reactivity is based on unboundEffect(EffectAction) callbacks that detect the signals used during invocation. The callback will be run again whenever there's a change to any of the signal instances used in the previous invocation. Detection is based on running get(). untracked(ValueSupplier) can be used to read the value within an effect without registering a dependency.

This interface can be used for creating simple computed signals as a lambda function that uses other signals. This kind of signal is more limited than computed(SignalComputation) since it doesn't cache its value.

  • Method Details

    • get

      T get()
      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 unboundEffect(EffectAction) or 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 untracked(ValueSupplier) block, or a transaction. Calling it outside such a context throws an IllegalStateException. Use peek() for one-time reads that do not need dependency tracking.

      Returns:
      the signal value
      Throws:
      IllegalStateException - if called outside a reactive context

    • peek

      default T peek()
      Reads the value without setting up any dependencies. This method returns the same value as get() but without creating a dependency when used inside a transaction, effect or computed signal.

      Unlike 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.

      Returns:
      the signal value

    • map

      default <C extends @Nullable Object> Signal<C> map(SignalMapper<T,C> mapper)
      Creates a simple computed signal based on a mapper function that is passed the value of this signal. If the mapper function accesses other signal values, then the computed signal will also depend on those signals.

      The computed signal does not perform any caching but will instead run the callback every time the signal value is read. Use computed(SignalComputation) to create a computed signal that caches the result of running the callback until the value of any dependency changes.

      Type Parameters:
      C - the computed signal type
      Parameters:
      mapper - the mapper function to use, not null
      Returns:
      the computed signal, not null

    • effect

      static <C extends Component> Registration effect(C owner, EffectAction effectFunction)
      Creates a signal effect that is owned by a given component. The effect is enabled when the component is attached and automatically disabled when it is detached.

      Example of usage: 

       Registration effect = Signal.effect(myComponent, () -> {
     Notification.show("Component is attached and signal value is "
             + someSignal.get());
 });
 effect.remove(); // to remove the effect when no longer needed
      Type Parameters:
      C - the type of the component
      Parameters:
      owner - the owner component for which the effect is applied, must not be null
      effectFunction - the effect function to be executed when any dependency is changed, must not be null
      Returns:
      a Registration that can be used to remove the effect function

    • unboundEffect

      static Registration unboundEffect(EffectAction action)
      Creates an unbound signal effect with the given action. The action is run when the effect is created and is subsequently run again whenever there's a change to any signal value that was read during the last invocation.

      An unbound effect executes without holding the session lock, similar to a background thread. If the effect action needs to modify components or other UI state, it must explicitly acquire the lock using UI.access(com.vaadin.flow.server.Command). This applies even when creating the effect while already holding the session lock, as the effect callbacks run independently and may execute after the session has expired or been invalidated.

      Consider using effect(Component, EffectAction) instead to tie the effect lifecycle to a component and automatically manage the session lock.

      Parameters:
      action - the effect action to use, not null
      Returns:
      a Registration that can be used to close the effect so that it no longer listens to signal changes, not null

    • computed

      static <T extends @Nullable Object> Signal<T> computed(SignalComputation<T> computation)
      Creates a new computed signal with the given computation callback. A computed signal behaves like a regular signal except that the value is not directly set but instead computed from other signals. The computed signal is automatically updated if any of the used signals are updated. The computation is lazy so that it only runs when its value is accessed and only if the previously computed value might have been invalidated by dependent signal changes. If the computation callback throws a RuntimeException, then that exception will be re-thrown when accessing the signal value. An effect or computed signal that uses the value from a computed signal will not be invalidated if the computation is run again but produces the same value as before.
      Type Parameters:
      T - the signal type
      Parameters:
      computation - the computation callback, not null
      Returns:
      the computed signal, not null

    • not

      static Signal<Boolean> not(Signal<Boolean> signal)
      Creates a new computed signal containing the negation of the provided boolean-valued signal.
      Parameters:
      signal - the boolean-valued signal to negate, not null
      Returns:
      the negated signal, not null

    • runInTransaction

      static <T extends @Nullable Object> TransactionOperation<T> runInTransaction(ValueSupplier<T> transactionTask)
      Runs the provided supplier in a transaction. All signal operations performed within the transaction will be staged and atomically committed at the end of the transaction. The commit fails and doesn't apply any of the commands if any of the commands fail. Reading a signal value within a transaction will make the transaction depend on that value so that the transaction fails if the signal value has been changed concurrently.

      The value returned by the supplier will be available from the returned operation instance. The result of the operation will be set based on whether the transaction was successfully committed once the status is confirmed.

      Type Parameters:
      T - the type returned by the supplier
      Parameters:
      transactionTask - the supplier to run, not null
      Returns:
      a transaction operation containing the supplier return value and the eventual result
      See Also:

    • runInTransaction

      static TransactionOperation<Void> runInTransaction(TransactionTask transactionTask)
      Runs the provided runnable in a transaction. All signal operations performed within the transaction will be staged and atomically committed at the end of the transaction. The commit fails and doesn't apply any of the commands if any of the commands fail. Reading a signal value within a transaction will make the transaction depend on that value so that the transaction fails if the signal value has been changed concurrently.

      The result of the operation will be set based on whether the transaction was successfully committed once the status is confirmed.

      Parameters:
      transactionTask - the runnable to run, not null
      Returns:
      a transaction operation containing the supplier return value and the eventual result
      See Also:

    • runWithoutTransaction

      static <T extends @Nullable Object> T runWithoutTransaction(ValueSupplier<T> task)
      Runs the given supplier outside any transaction and returns the supplied value. The current transaction will be restored after the task has been run.
      Type Parameters:
      T - the supplier type
      Parameters:
      task - the supplier to run, not null
      Returns:
      the value returned from the supplier

    • runWithoutTransaction

      static void runWithoutTransaction(TransactionTask task)
      Runs the given task outside any transaction. The current transaction will be restored after the task has been run.
      Parameters:
      task - the task to run, not null

    • untracked

      static <T extends @Nullable Object> T untracked(ValueSupplier<T> task)
      Runs the given supplier without tracking dependencies for signals that are read within the supplier. This has the same effect as peek() but is effective for an entire code block rather than just a single invocation.
      Type Parameters:
      T - the supplier type
      Parameters:
      task - the supplier task to run, not null
      Returns:
      the value returned from the supplier