Package com.vaadin.signals

Interface Signal<T>

Type Parameters:
T - the signal value type
All Known Implementing Classes:
AbstractSignal, ComputedSignal, ListSignal, MapSignal, NodeSignal, NumberSignal, 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>
A signal is a reactive value holder with automatic subscription and unsubscription of listeners.

Reactivity is based on effect(Runnable) 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 value(). untracked(Supplier) 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(Supplier) since it doesn't cache its value.

  • Method Details

    • value

      T value()
      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 effect(Runnable) or computed(Supplier) callback sets up that effect or computed signal to depend on the signal.

      Returns:
      the signal value

    • map

      default <C> Signal<C> map(Function<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(Supplier) 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 Runnable effect(Runnable action)
      Creates a 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.
      Parameters:
      action - the effect action to use, not null
      Returns:
      a callback used to close the effect so that it no longer listens to signal changes, not null

    • computed

      static <T> Signal<T> computed(Supplier<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

    • runInTransaction

      static <T> TransactionOperation<T> runInTransaction(Supplier<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(Runnable 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> T runWithoutTransaction(Supplier<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(Runnable 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> T untracked(Supplier<T> task)
      Runs the given supplier without tracking dependencies for signals that are read within the supplier. This has the same effect as AbstractSignal.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