com.vaadin.signals.

Class NodeSignal

public class NodeSignal extends Signal<NodeSignal.NodeSignalState>

A signal representing a node in a tree structure. The Signal.value() of a node signal is an immutable object that consists of:

  • the node's own value
  • the parent node
  • child nodes accessed by order (list children)
  • child nodes accessed by key (map children
A child node is always either a list child or a map child but it cannot have both roles at the same time. The Signal.value() of a detached node is null.

This class does not provide methods for all possible operation you could do with a signal but only for the operations that have some special meaning in the context of a node in a tree. You can use the various as methods to get an instance of that specific type that you can use for applying some specific operation.

  • Constructor Details

    • NodeSignal

      public NodeSignal()

      Creates a new empty node signal that serves as a root for a hierarchical node structure. The signal does not support clustering.

    • NodeSignal

      protected NodeSignal(SignalTree tree, Id id, Predicate<SignalCommand> validator)

      Creates a new node signal based on the given tree, node id and validator.

      Parameters:

      tree - the tree to use, not null

      id - the node id to use, not null

      validator - the validator to check operations submitted to this singal, not null

  • Method Details

    • extractValue

      protected NodeSignal.NodeSignalState extractValue(Node.Data data)

      Description copied from class: Signal

      Extracts the value for this signal from the given signal data node.

      Specified by:

      extractValue in class Signal<NodeSignal.NodeSignalState>

      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: Signal

      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 Signal.value() of this signal changes.

      Specified by:

      usageChangeValue in class Signal<NodeSignal.NodeSignalState>

      Parameters:

      data - the data node to read from, not null

      Returns:

      a reference value to use for validity checks, may be null

    • asValue

      public <T> ValueSignal<T> asValue(Class<T> valueType)

      Creates a value signal backed by the node value of this node. The value of the value signal is the same as NodeSignal.NodeSignalState.value(Class) of this signal. The new signal uses the same validator as this signal.

      Type Parameters:

      T - the value type

      Parameters:

      valueType - the value type, not null

      Returns:

      this signal as a value signal, not null

    • asNumber

      public NumberSignal asNumber()

      Creates a number signal backed by the node value of this node. The value of the number signal is the same as NodeSignal.NodeSignalState.value(Class) of this signal. The new signal uses the same validator as this signal. Accessing the value of the signal will throw an exception if the underlying value is not a JSON number.

      Returns:

      this signal as a number signal, not null

    • asList

      public <T> ListSignal<T> asList(Class<T> elementType)

      Creates a list signal backed by the list children of this node. The value of the list signal is the same as NodeSignal.NodeSignalState.listChildren() of this signal. The new signal uses the same validator as this signal. Accessing the value of child signal will throw an exception if the underlying value cannot be JSON deserialized as the provided element type.

      Type Parameters:

      T - the element type

      Parameters:

      elementType - the element type, not null

      Returns:

      this signal as a list signal, not null

    • asMap

      public <T> MapSignal<T> asMap(Class<T> elementType)

      Creates a map signal backed by the map children of this node. The value of the map signal is the same as NodeSignal.NodeSignalState.mapChildren() of this signal. The new signal uses the same validator as this signal.Accessing the value of child signal will throw an exception if the underlying value cannot be JSON deserialized as the provided element type.

      Type Parameters:

      T - the element type

      Parameters:

      elementType - the element type, not null

      Returns:

      this signal as a map signal, not null

    • insertChildWithValue

      public InsertOperation<NodeSignal> insertChildWithValue(Object value, ListSignal.ListPosition at)

      Inserts a new node with the given value as a list node at the given list position. The operation fails if the position is not valid at the time when the operation is processed.

      Parameters:

      value - the value to insert

      at - the insert position, not null

      Returns:

      an operation containing a signal for the inserted entry and the eventual result

    • insertChild

      Inserts a new node with no value as a list node at the given list position. The operation fails if the position is not valid at the time when the operation is processed.

      Parameters:

      at - the insert position, not null

      Returns:

      an operation containing a signal for the inserted entry and the eventual result

    • putChildWithValue

      public SignalOperation<Void> putChildWithValue(String key, Object value)

      Associates the given value with the given key. If a map child already exists for the given key, then the value of that node is updated. If no map child exists, then a new node is created with the given value.

      Note that this operation does not give direct access to the child signal that was created or updated. Use putChildWithValue(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

    • putChildIfAbsent

      public InsertOperation<NodeSignal> putChildIfAbsent(String key)

      Creates a new node with no value if a map node with the given key doesn't already exist. The returned operation has a reference to a signal that corresponds to the given key regardless of whether a node existed for the key. The operation will be resolved as successful regardless of whether the key was already used.

      Parameters:

      key - the key to use, not null

      Returns:

      an operation containing a signal for the entry and the eventual result

    • adoptAt

      public SignalOperation<Void> adoptAt(Signal<?> node, ListSignal.ListPosition at)

      Adopts the given node as a list child at the given location. The node must be a member of the same node tree. It will be detached from its current location in the tree. The operation fails if the position is not valid at the time when the operation is processed.

      Parameters:

      node - the signal to adopt, not null

      at - the target list location, not null

      Returns:

      an operation containing the eventual result

    • adoptAs

      public SignalOperation<Void> adoptAs(Signal<?> signal, String key)

      Adopts the given node as a map child with the given key. The node must be a member of the same node tree. It will be detached from its current location in the tree. The operation fails if there is already a map child with the same key at the time when the operation is processed.

      Parameters:

      signal - the signal to adopt, not null

      key - the key to use, not null

      Returns:

      an operation containing the eventual result

    • removeChild

      public SignalOperation<Void> removeChild(NodeSignal child)

      Removes the given child from this node. The operation fails if the child is not a child of this node at the time when the operation is processed.

      Parameters:

      child - the child to remove, not null

      Returns:

      an operation containing the eventual result

    • removeChild

      public SignalOperation<Void> removeChild(String key)

      Removes the map child with the given key. The operation will be resolved as successful if a mapping existed and as a failure if there was no mapping 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 list children and map children from this node.

      Overrides:

      clear in class Signal<NodeSignal.NodeSignalState>

      Returns:

      an operation containing the eventual result

    • withValidator

      public NodeSignal withValidator(Predicate<SignalCommand> 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.

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

    • asReadonly

      public NodeSignal asReadonly()

      Wraps this signal to not accept changes. Child node 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 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