Package com.vaadin.signals.impl

Class SignalTree

java.lang.Object
com.vaadin.signals.impl.SignalTree
Direct Known Subclasses:
AsynchronousSignalTree, SynchronousSignalTree
public abstract class SignalTree extends Object
Provides thread-safe access to a tree of signal nodes and a way of listening for changes to those nodes. There are two primary types of signal trees: synchronous trees have their changes applied immediately whereas asynchronous trees make a differences between submitted changes and changes that have been asynchronously confirmed.

  • Constructor Details

    • SignalTree

      protected SignalTree(SignalTree.Type type)
      Creates a new signal tree with the given type.
      Parameters:
      type - the signal tree type, not null

  • Method Details

    • id

      public Id id()
      Gets the id of this signal tree. The id is a randomly generated unique value. The id is mainly used for identifying node ownership.
      Returns:
      the tree id, not null
      See Also:

    • getLock

      public ReentrantLock getLock()
      Gets the lock that is used for protecting the integrity of this signal tree. Locking is in general handled automatically by the tree but needs to be handled externally when applying transactions so that all trees participating in a transaction are locked before starting to evaluate the transaction.
      Returns:
      the tree lock instance, not null

    • hasLock

      protected boolean hasLock()
      Checks whether the tree lock is currently held.
      Returns:
      true if the lock is held by the current thread

    • getWithLock

      protected <T> T getWithLock(Supplier<T> action)
      Runs a supplier while holding the lock and returns the provided value.
      Type Parameters:
      T - the supplier type
      Parameters:
      action - the supplier to run, not null
      Returns:
      the value returned by the supplier

    • runWithLock

      protected void runWithLock(Runnable action)
      Runs an action while holding the lock.
      Parameters:
      action - the action to run, not null

    • wrapWithLock

      protected Runnable wrapWithLock(Runnable action)
      Wraps the provided action to run it while holding the lock.
      Parameters:
      action - the action to wrap, not null
      Returns:
      a runnable that runs the provided action while holding the lock, not null

    • observeNextChange

      public Runnable observeNextChange(Id nodeId, TransientListener observer)
      Registers an observer for a node in this tree. The observer will be invoked the next time the corresponding node is updated in the submitted snapshot. The observer is removed when invoked and needs to be registered again if it's still relevant unless it returns true. It is safe to register the observer again from within the callback.
      Parameters:
      nodeId - the id of the node to observe, not null
      observer - the callback to run when the node has changed, not null
      Returns:
      a callback that can be used to remove the observer before it's triggered, not null

    • notifyObservers

      protected void notifyObservers(Snapshot oldSnapshot, Snapshot newSnapshot)
      Notify all observers that are affected by changes between two snapshots. All notified observers are removed. It is safe for an observer to register itself again when it is invoked.
      Parameters:
      oldSnapshot - the old snapshot, not null
      newSnapshot - the new snapshot, not null
      See Also:

    • submitted

      public abstract Snapshot submitted()
      Gets the current snapshot based on all confirmed and submitted commands.
      Returns:
      the submitted snapshot, not null

    • confirmed

      public abstract Snapshot confirmed()
      Gets the current snapshot based on all confirmed commands. This snapshot does not contain changes from commands that have been submitted but not yet confirmed.
      Returns:
      the confirmed snapshot, not null

    • commitSingleCommand

      public void commitSingleCommand(SignalCommand command, Consumer<CommandResult> resultHandler)
      Applies a single command to this tree. This is a shorthand for committing only a single command.
      Parameters:
      command - the command to apply, not null
      resultHandler - a result handler that will be notified when the command is confirmed, not null to ignore the result

    • commitSingleCommand

      public void commitSingleCommand(SignalCommand command)
      Applies a single command to this tree without listening for the result.
      Parameters:
      command - the command to apply, not null
      See Also:

    • prepareCommit

      public abstract SignalTree.PendingCommit prepareCommit(CommandsAndHandlers changes)
      Starts the process of committing a set of changes. The returned instance defines callbacks for continuing the commit procedure.

      Note that this method expects that the caller has acquired the tree lock prior to calling the method and that the lock will remain acquired while interacting with the returned object.

      Parameters:
      changes - the changes to commit, not null
      Returns:
      callbacks for coordinating the rest of the commit sequence, not null

    • type

      public SignalTree.Type type()
      Gets the type of this signal tree.
      Returns:
      the signal tree type, not null

    • subscribeToProcessed

      public Runnable subscribeToProcessed(BiConsumer<SignalCommand,CommandResult> subscriber)
      Registers a callback that is executed after commands are processed (regardless of acceptance or rejection). It is guaranteed that the callback is invoked in the order the commands are processed. Contrary to the observers that are attached to a specific node by calling observeNextChange(com.vaadin.signals.Id, com.vaadin.signals.impl.TransientListener), the subscriber remains active indefinitely until it is removed by executing the returned callback.
      Parameters:
      subscriber - the callback to run when a command is confirmed, not null
      Returns:
      a callback that can be used to remove the subscriber, not null

    • notifyProcessedCommandSubscribers

      protected void notifyProcessedCommandSubscribers(List<SignalCommand> commands, Map<Id,CommandResult> results)
      Notifies all subscribers after a command is processed. This method must be called from a code block that holds the tree lock.
      Parameters:
      commands - the list of processed commands, not null
      results - the map of results for the commands, not null