Package com.vaadin.flow.signals.shared

Class AbstractSharedSignal<T extends @Nullable Object>

java.lang.Object
com.vaadin.flow.signals.shared.AbstractSharedSignal<T>
Type Parameters:
T - the signal value type
All Implemented Interfaces:
Signal<T>, Serializable
Direct Known Subclasses:
CachedSignal, SharedListSignal, SharedMapSignal, SharedNodeSignal, SharedValueSignal
public abstract class AbstractSharedSignal<T extends @Nullable Object> extends Object implements Signal<T>
Base type for full-featured signals that are backed by a transactional signal tree.

This signal may be synchronized across a cluster. In that case, changes to the signal value are only confirmed asynchronously. The regular signal get() returns the assumed value based on local modifications whereas peekConfirmed() gives access to the confirmed value.

Since:
25.1
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static interface 
    AbstractSharedSignal.ChildSignalFactory<I extends AbstractSharedSignal<?>>
    Creates a child signal instance from a node ID.
    protected static interface 
    AbstractSharedSignal.ResultConverter<T extends @Nullable Object>
    Converts a command result into a specific value type.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final CommandValidator
    ANYTHING_GOES
    Signal validator that accepts anything.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractSharedSignal(SignalTree tree, Id id, CommandValidator validator)
    Creates a new signal instance with the given id and validator for the given signal tree.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected SharedNodeSignal
    asNode()
    Converts this signal into a node signal.
    protected SignalOperation<Void>
    clear()
    Helper to submit a clear command.
    protected static tools.jackson.databind.JavaType
    constructType(Class<?> type)
    Resolves the given class into a type definition that can be used for reading signal values.
    protected static tools.jackson.databind.JavaType
    constructType(tools.jackson.core.type.TypeReference<?> typeReference)
    Resolves the given type reference into a type definition that can be used for reading signal values.
    protected UsageTracker.Usage
    createUsage(Transaction transaction)
    Creates a usage instance based on the current state of this signal.
    protected @Nullable Node.Data
    data(Transaction transaction)
    Gets the data node for this signal in the given transaction.
    protected @Nullable Node.Data
    data(TreeRevision revision)
    Gets the data node for this signal in the given tree revision.
    protected abstract @Nullable T
    extractValue(@Nullable Node.Data data)
    Extracts the value for this signal from the given signal data node.
    protected static <T> @Nullable T
    fromJson(@Nullable tools.jackson.databind.JsonNode value, Class<T> targetType)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use fromJson(JsonNode, JavaType) instead, which also retains the type arguments of a parameterized type such as Set<String>
    protected static <T> @Nullable T
    fromJson(@Nullable tools.jackson.databind.JsonNode value, tools.jackson.databind.JavaType targetType)
    Helper to convert the given JSON to a Java instance of the given type using the global signal object mapper.
    T
    get()
    Gets the current value of this signal.
    Id
    id()
    Gets the unique id of this signal instance.
    protected CommandValidator
    mergeValidators(CommandValidator validator)
    Merges the validator used by this signal with the given validator.
    protected static <T> @Nullable T
    nodeValue(Node node, Class<T> valueType)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use nodeValue(Node, JavaType) instead, which also retains the type arguments of a parameterized type such as Set<String>
    protected static <T> @Nullable T
    nodeValue(Node node, tools.jackson.databind.JavaType valueType)
    Helper to convert the value of the given node into Java object of the given type.
    T
    peek()
    Reads the value without setting up any dependencies.
    T
    peekConfirmed()
    Reads the confirmed value without setting up any dependencies.
    protected SignalOperation<Void>
    remove(AbstractSharedSignal<?> child)
    Helper to submit a remove command.
    protected SignalOperation<Void>
    submit(SignalCommand command)
    Submits a command for this signal and updates the created operation without a value once the command result is confirmed.
    protected <R> SignalOperation<R>
    submit(SignalCommand command, AbstractSharedSignal.ResultConverter<R> resultConverter)
    Submits a command for this signal and uses the provided result converter to updates the created operation once the command result is confirmed.
    protected <R, O extends SignalOperation<R>>
    O
    submit(SignalCommand command, AbstractSharedSignal.ResultConverter<R> resultConverter, O operation)
    Submits a command for this signal and updates the given operation using the given result converter once the command result is confirmed.
    protected <I extends AbstractSharedSignal<?>>
    InsertOperation<I>
    submitInsert(SignalCommand command, AbstractSharedSignal.ChildSignalFactory<I> childFactory)
    Submits a command for this signal and creates and insert operation that is updated once the command result is confirmed.
    protected <O extends SignalOperation<Void>>
    O
    submitVoidOperation(SignalCommand command, O operation)
    Submits a command for this signal and updates the given operation without a value once the command result is confirmed.
    protected static tools.jackson.databind.JsonNode
    toJson(@Nullable Object value)
    Helper to convert the given object to JSON using the global signal object mapper.
    protected SignalTree
    tree()
    Gets the signal tree that stores the value for this signal.
    protected abstract @Nullable Object
    usageChangeValue(Node.Data data)
    Gets a reference value that will be used to determine whether a dependency based on previous usage should be invalidated.
    protected CommandValidator
    validator()
    Gets the validator used by this signal instance.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.vaadin.flow.signals.Signal

    map

  • Field Details

    • ANYTHING_GOES

      protected static final CommandValidator ANYTHING_GOES
      Signal validator that accepts anything. This is defined as a constant to enable using == to detect and optimize cases where no validation is applied.

  • Constructor Details

    • AbstractSharedSignal

      protected AbstractSharedSignal(SignalTree tree, Id id, CommandValidator validator)
      Creates a new signal instance with the given id and validator for the given signal tree.
      Parameters:
      tree - the signal tree that contains the value for this signal, not null
      id - the id of the signal node within the signal tree, not null
      validator - the validator to check operations submitted to this singal, not null

  • Method Details

    • data

      protected @Nullable Node.Data data(TreeRevision revision)
      Gets the data node for this signal in the given tree revision.
      Parameters:
      revision - the tree revision to read from, not null
      Returns:
      the data node, or null if there is no node for this signal in the revision

    • data

      protected @Nullable Node.Data data(Transaction transaction)
      Gets the data node for this signal in the given transaction.
      Parameters:
      transaction - the transaction to read from, not null
      Returns:
      the data node, or null if there is no node for this signal in the transaction

    • get

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

      Specified by:
      get in interface Signal<T extends @Nullable Object>
      Returns:
      the signal value

    • peek

      public T peek()
      Description copied from interface: Signal
      Reads the value without setting up any dependencies. This method returns the same value as Signal.get() but without creating a dependency when used inside a transaction, effect or cached signal.

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

      Specified by:
      peek in interface Signal<T extends @Nullable Object>
      Returns:
      the signal value

    • peekConfirmed

      public T peekConfirmed()
      Reads the confirmed value without setting up any dependencies. The confirmed value doesn't consider changes in the current transaction or changes that have been submitted but not yet confirmed in a cluster.
      Returns:
      the confirmed signal value

    • validator

      protected CommandValidator validator()
      Gets the validator used by this signal instance.
      Returns:
      the used validator, not null

    • mergeValidators

      protected CommandValidator mergeValidators(CommandValidator validator)
      Merges the validator used by this signal with the given validator. This chains the two validators so that both must accept any change but it additionally avoids redundant chaining in case either validator is ANYTHING_GOES.
      Parameters:
      validator - the validator to merge, not null
      Returns:
      a combined validator, not null

    • extractValue

      protected abstract @Nullable T extractValue(@Nullable Node.Data data)
      Extracts the value for this signal from the given signal data node.
      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 abstract @Nullable Object usageChangeValue(Node.Data data)
      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 get() of this signal changes.

      Parameters:
      data - the data node to read from, not null
      Returns:
      a reference value to use for validity checks, may be null

    • submit

      protected <R, O extends SignalOperation<R>> O submit(SignalCommand command, AbstractSharedSignal.ResultConverter<R> resultConverter, O operation)
      Submits a command for this signal and updates the given operation using the given result converter once the command result is confirmed. The command is submitted through the current Transaction and it uses SignalEnvironment.getCurrentResultNotifier() for delivering the result update.
      Type Parameters:
      R - the result type
      O - the operation type
      Parameters:
      command - the command to submit, not null
      resultConverter - a callback for creating an operation result value based on the command result, not null
      operation - the operation to update with the eventual result, not null
      Returns:
      the provided operation, for chaining

    • submitVoidOperation

      protected <O extends SignalOperation<Void>> O submitVoidOperation(SignalCommand command, O operation)
      Submits a command for this signal and updates the given operation without a value once the command result is confirmed. This is a shorthand for submit(SignalCommand, ResultConverter, SignalOperation) in the case of operations that don't have a result value.
      Type Parameters:
      O - the operation type
      Parameters:
      command - the command to submit, not null
      operation - the operation to update with the eventual result, not null
      Returns:
      the provided operation, for chaining

    • submitInsert

      protected <I extends AbstractSharedSignal<?>> InsertOperation<I> submitInsert(SignalCommand command, AbstractSharedSignal.ChildSignalFactory<I> childFactory)
      Submits a command for this signal and creates and insert operation that is updated once the command result is confirmed. This is a shorthand for submit(SignalCommand, ResultConverter, SignalOperation) in the case of insert operations.
      Type Parameters:
      I - the insert operation type
      Parameters:
      command - the command to submit, not null
      childFactory - callback used to create a signal instance in the insert operation, not null
      Returns:
      the created insert operation, not null

    • submit

      protected <R> SignalOperation<R> submit(SignalCommand command, AbstractSharedSignal.ResultConverter<R> resultConverter)
      Submits a command for this signal and uses the provided result converter to updates the created operation once the command result is confirmed. This is a shorthand for submit(SignalCommand, ResultConverter, SignalOperation) in the case of using the default operation type.
      Type Parameters:
      R - the operation result value
      Parameters:
      command - the command to submit, not null
      resultConverter - a callback for creating an operation result value based on the command result, not null
      Returns:
      the created operation instance, not null

    • submit

      protected SignalOperation<Void> submit(SignalCommand command)
      Submits a command for this signal and updates the created operation without a value once the command result is confirmed. This is a shorthand for submit(SignalCommand, ResultConverter, SignalOperation) in the case of using the default operation type and no result value.
      Parameters:
      command - the command to submit, not null
      Returns:
      the created operation instance, not null

    • id

      public Id id()
      Gets the unique id of this signal instance. The id will be the same for other signal instances backed by the same data, e.g. in the case of using asNode() to create a signal of different type.
      Returns:
      the signal id, not null

    • tree

      protected SignalTree tree()
      Gets the signal tree that stores the value for this signal.
      Returns:
      the signal tree, not null

    • createUsage

      protected UsageTracker.Usage createUsage(Transaction transaction)
      Creates a usage instance based on the current state of this signal.
      Parameters:
      transaction - the transaction for which the usage occurs, not null
      Returns:
      a usage instance, not null

    • asNode

      protected SharedNodeSignal asNode()
      Converts this signal into a node signal. This allows further conversion into any specific signal type through the methods in SharedNodeSignal. The converted signal is backed by the same underlying data and uses the same validator as this signal.
      Returns:
      this signal as a node signal, not null

    • clear

      protected SignalOperation<Void> clear()
      Helper to submit a clear command. This is a helper is re-defined as public in the signal types where a clear operation makes sense.
      Returns:
      the created signal operation instance, not null

    • remove

      protected SignalOperation<Void> remove(AbstractSharedSignal<?> child)
      Helper to submit a remove command. This is a helper is re-defined as public in the signal types where a remove operation makes sense.
      Parameters:
      child - the child signal to remove, not null
      Returns:
      the created signal operation instance, not null

    • toJson

      protected static tools.jackson.databind.JsonNode toJson(@Nullable Object value)
      Helper to convert the given object to JSON using the global signal object mapper.
      Parameters:
      value - the object to convert to JSON
      Returns:
      the converted JSON node, not null
      See Also:

    • fromJson

      @Deprecated(since="25.3", forRemoval=true) protected static <T> @Nullable T fromJson(@Nullable tools.jackson.databind.JsonNode value, Class<T> targetType)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use fromJson(JsonNode, JavaType) instead, which also retains the type arguments of a parameterized type such as Set<String>
      Helper to convert the given JSON to a Java instance of the given type using the global signal object mapper.
      Type Parameters:
      T - the target type
      Parameters:
      value - the JSON value to convert
      targetType - the target type, not null
      Returns:
      the converted Java instance
      See Also:

    • fromJson

      protected static <T> @Nullable T fromJson(@Nullable tools.jackson.databind.JsonNode value, tools.jackson.databind.JavaType targetType)
      Helper to convert the given JSON to a Java instance of the given type using the global signal object mapper. The type arguments of a parameterized type such as Set<String> are retained.
      Type Parameters:
      T - the target type
      Parameters:
      value - the JSON value to convert
      targetType - the target type, not null
      Returns:
      the converted Java instance
      Since:
      25.3
      See Also:

    • constructType

      protected static tools.jackson.databind.JavaType constructType(Class<?> type)
      Resolves the given class into a type definition that can be used for reading signal values.
      Parameters:
      type - the class to resolve, not null
      Returns:
      the resolved type, not null
      Since:
      25.3

    • constructType

      protected static tools.jackson.databind.JavaType constructType(tools.jackson.core.type.TypeReference<?> typeReference)
      Resolves the given type reference into a type definition that can be used for reading signal values. The type arguments of a parameterized type such as Set<String> are retained.
      Parameters:
      typeReference - the type reference to resolve, not null
      Returns:
      the resolved type, not null
      Since:
      25.3

    • nodeValue

      @Deprecated(since="25.3", forRemoval=true) protected static <T> @Nullable T nodeValue(Node node, Class<T> valueType)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use nodeValue(Node, JavaType) instead, which also retains the type arguments of a parameterized type such as Set<String>
      Helper to convert the value of the given node into Java object of the given type.
      Type Parameters:
      T - the Java object type
      Parameters:
      node - the signal node to read the value from, not null
      valueType - the type to convert to, not null
      Returns:
      the converted Java instance

    • nodeValue

      protected static <T> @Nullable T nodeValue(Node node, tools.jackson.databind.JavaType valueType)
      Helper to convert the value of the given node into Java object of the given type. The type arguments of a parameterized type such as Set<String> are retained.
      Type Parameters:
      T - the Java object type
      Parameters:
      node - the signal node to read the value from, not null
      valueType - the type to convert to, not null
      Returns:
      the converted Java instance
      Since:
      25.3