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, AbstractSharedSignal, CachedSignal, 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.

  • 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 cached(Signal) callback sets up that effect or cached signal to depend on the signal.

      This method must only be called within a reactive context such as an effect, cached 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 cached 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.
      Type Parameters:
      C - the computed signal type
      Parameters:
      mapper - the mapper function to use, not null
      Returns:
      the computed signal, not null

    • effect

      static Registration effect(Component 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
      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

    • effect

      static Registration effect(Component owner, ContextualEffectAction effectFunction)
      Creates a context-aware component-scoped signal effect. The effect is enabled when the component is attached and automatically disabled when it is detached. The action receives an EffectContext providing information about why the effect is running (initial render, effect owner's request, or background change).

      Example of usage: 

       Signal.effect(this, ctx -> {
     span.getElement().setText("$" + price.get());
     if (ctx.isBackgroundChange()) {
         span.getElement().flashClass("highlight");
     }
 });
      Parameters:
      owner - the owner component for which the effect is applied, must not be null
      effectFunction - the context-aware effect function, 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 value is computed again every time the value is read. Use cached(Signal) to create a signal that computes a new value only if any of the dependent signals might have changed.

      A computed signal can also be defined directly as a lambda expression. Using this method enables type inference in cases where the target type isn't explicitly defined. 

       // Type must be explicitly defined for a direct lambda expression
 Signal<Integer> signal = () -> stringSignal.get().length();
 
 // Type can be inferred by wrapping in computed()
 var signal = Signal.computed(() -> stringSignal.get().length());
      Type Parameters:
      T - the signal type
      Parameters:
      computation - the computation callback, not null
      Returns:
      the computed signal, not null

    • cached

      static <T extends @Nullable Object> Signal<T> cached(Signal<T> innerSignal)
      Creates a new cached signal based on the given inner signal. The inner signal is typically a computed signal performing an expensive computation based on other signal values. When getting the value of this signal, a previously cached value will be used if available as long as that value is still valid. The cached value remains valid until the value changes for any of the inner signals.

      If a RuntimeException is thrown when getting the value of the inner signal, then that exception will be re-thrown when accessing the value of this signal. An effect or outer cached signal that uses the value from a cached signal will not be invalidated if the inner signal is invalidated but holds the same value as before invalidation.

      Type Parameters:
      T - the signal type
      Parameters:
      innerSignal - the inner signal, not null
      Returns:
      the cached 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