Class StateNode

java.lang.Object
com.vaadin.flow.internal.StateNode
All Implemented Interfaces:
Serializable

public class StateNode extends Object implements Serializable
A node in the state tree that is synchronized with the client-side. Data stored in nodes is structured into different features to provide isolation. The features available for a node are defined when the node is created.

For internal use only. May be renamed or removed in a future release.

Since:
1.0
Author:
Vaadin Ltd
See Also:
  • Constructor Details

    • StateNode

      @SafeVarargs public StateNode(Class<? extends NodeFeature>... featureTypes)
      Creates a state node with the given feature types.
      Parameters:
      featureTypes - a collection of feature classes that the node should support
    • StateNode

      public StateNode(StateNode node)
      Create a new instance using the same features as provided node declares.
      Parameters:
      node - the node whose features set will be copied
    • StateNode

      @SafeVarargs public StateNode(List<Class<? extends NodeFeature>> reportableFeatureTypes, Class<? extends NodeFeature>... additionalFeatureTypes)
      Creates a state node with the given feature types and required features that are always sent to the client side.
      Parameters:
      reportableFeatureTypes - the list of the features that are required on the client side (populated even if they are empty)
      additionalFeatureTypes - a collection of feature classes that the node should support. May, but is not required to, also include reportable feature types.
  • Method Details

    • getOwner

      public NodeOwner getOwner()
      Gets the node owner that this node currently belongs to.
      Returns:
      the node owner
    • getParent

      public StateNode getParent()
      Gets the parent node that this node belongs to.
      Returns:
      the current parent node; null if the node is not attached to a parent node, or if this node is the root of a state tree.
    • setParent

      public void setParent(StateNode parent)
      Sets the parent node that this node belongs to. This node is set to belong to the node owner of the parent node. The node still retains its owner when the parent is set to null.
      Parameters:
      parent - the new parent of this node; or null if this node is not attached to another node
    • onAttach

      protected void onAttach()
      Called when this node has been attached to a state tree.
    • forEachChild

      public void forEachChild(Consumer<StateNode> action)
      Executes the given action for each child node of this state node.
      Parameters:
      action - the action to execute, not null
    • setTree

      protected void setTree(StateTree tree)
      Sets the state tree that this node belongs to.
      Parameters:
      tree - the state tree
    • removeFromTree

      public void removeFromTree()
      Removes the node from its parent and unlinks the node (and children) from the state tree.
    • prepareForResync

      protected void prepareForResync()
      Prepares the tree below this node for resynchronization by detaching all descendants, setting their internal state to not yet attached, and calling the attach listeners.
    • getFeature

      public <T extends NodeFeature> T getFeature(Class<T> featureType)
      Gets the feature of the given type, creating one if necessary. This method throws IllegalStateException if this node isn't configured to use the desired feature. Use hasFeature(Class) to check whether a node is configured to use a specific feature.
      Type Parameters:
      T - the desired feature type
      Parameters:
      featureType - the desired feature type, not null
      Returns:
      a feature instance, not null
    • getFeatureIfInitialized

      public <T extends NodeFeature> Optional<T> getFeatureIfInitialized(Class<T> featureType)
      Gets the feature of the given type if it has been initialized. This method throws IllegalStateException if this node isn't configured to use the desired feature. Use hasFeature(Class) to check whether a node is configured to use a specific feature.
      Type Parameters:
      T - the desired feature type
      Parameters:
      featureType - the desired feature type, not null
      Returns:
      a feature instance, or an empty optional if the feature is not yet initialized for this node
    • hasFeature

      public boolean hasFeature(Class<? extends NodeFeature> featureType)
      Checks whether this node contains a feature.
      Parameters:
      featureType - the feature type to check for
      Returns:
      true if this node contains the feature; otherwise false
    • getId

      public int getId()
      Gets the id of this node. The id is unique within the state tree that the node belongs to. The id is 0 if the node does not belong to any state tree.
      Returns:
      the node id
      See Also:
    • markAsDirty

      public void markAsDirty()
      Marks this node as dirty.
      See Also:
    • isAttached

      public boolean isAttached()
      Checks whether this node is attached to a state tree.
      Returns:
      true if this node is attached; false if this node is not attached
    • collectChanges

      public void collectChanges(Consumer<NodeChange> collector)
      Collects all changes made to this node since the last time collectChanges(Consumer) has been called. If the node is recently attached, then the reported changes will be relative to a newly created node.

      WARNING: this is in fact an internal (private method) which is expected to be called from StateTree.collectChanges(Consumer) method only (which is effectively private itself). Don't call this method from any other place because it will break the expected UI state.

      Parameters:
      collector - a consumer accepting node changes
    • clearChanges

      public void clearChanges()
      Clears all changes recorded for this node. This method is public only for testing purposes.
    • visitNodeTree

      public void visitNodeTree(Consumer<StateNode> visitor)
      Applies the visitor to this node and all its descendants.

      The visitor is first applied to this node (root) and then to children.

      Parameters:
      visitor - visitor to apply
    • addAttachListener

      public Registration addAttachListener(Command attachListener)
      Adds a command as an attach listener. It is executed whenever this state node is attached to the state tree.
      Parameters:
      attachListener - the attach listener to add
      Returns:
      an event registration handle for removing the listener
    • addDetachListener

      public Registration addDetachListener(Command detachListener)
      Adds a command as a detach listener. It is executed whenever this state node is detached from the state tree.
      Parameters:
      detachListener - the detach listener to add
      Returns:
      an event registration handle for removing the listener
    • getChangeTracker

      public <T extends Serializable> T getChangeTracker(NodeFeature feature, Supplier<T> factory)
      Gets or creates a change tracker object for the provided feature.
      Type Parameters:
      T - the change tracker type
      Parameters:
      feature - the feature for which to get a change tracker
      factory - a factory method used to create a new tracker if there isn't already one
      Returns:
      the change tracker to use
    • runWhenAttached

      public void runWhenAttached(SerializableConsumer<UI> command)
      Runs the command when the node is attached to a UI.

      If the node is already attached when this method is called, the method is run immediately.

      Parameters:
      command - the command to run immediately or when the node is attached
    • isReportedFeature

      public boolean isReportedFeature(Class<? extends NodeFeature> featureType)
      Returns whether the featureType should be reported to the client even if it doesn't contain any data.
      Parameters:
      featureType - feature type which needs to be populated on the client
      Returns:
      whether the feature required by the client side
    • updateActiveState

      public void updateActiveState()
      Update "active"/"inactive" state of the node.

      The node is considered as inactive if there is at least one feature whose NodeFeature.allowsChanges() method returns false or it has inactive ascendant.

      Inactive nodes should restrict their RPC communication with client: only features that returns false via their method allowsChanges() and reported features send their changes while the node is inactive (the latter features are necessary on the client side to be able to find a strategy which has to be selected to handle the node).

      Implementation Note: this is done as a separate method instead of calculating the state on the fly (checking all features) because each node needs to check this status on its own AND on its parents (may be all parents up to the root).

      See Also:
    • isInactive

      public boolean isInactive()
      Checks whether the node is active.

      Inactive node should not participate in any RPC communication.

      Returns:
      true if the node is inactive
    • isVisible

      public boolean isVisible()
      Checks (recursively towards the parent node) whether the node is effectively visible.

      Non-visible node should not participate in any RPC communication.

      Returns:
      true if the node is effectively visible
    • isInert

      public boolean isInert()
      Returns whether or not this state node is inert and it should not receive any updates from the client side. Inert state is inherited from parent, unless explicitly set to ignore parent inert state.

      The inert state is only updated when the changes are written to the client side, but the inert state is not sent to the client side - it is a server side feature only.

      Returns:
      true if the node is inert, false if not
      See Also:
    • hasBeforeClientResponseEntries

      public boolean hasBeforeClientResponseEntries()
      Checks whether there are pending executions for this node.
      Returns:
      true if there are pending executions, otherwise false
      See Also:
    • dumpBeforeClientResponseEntries

      public List<StateTree.BeforeClientResponseEntry> dumpBeforeClientResponseEntries()
      Gets the current list of pending execution entries for this node and clears the current list.
      Returns:
      the current list of entries, or and empty list if there are no entries
      See Also:
    • addBeforeClientResponseEntry

      public StateTree.ExecutionRegistration addBeforeClientResponseEntry(StateTree.BeforeClientResponseEntry entry)
      Adds an entry to be executed before the next client response for this node. Entries should always be created through StateTree.beforeClientResponse(StateNode, com.vaadin.flow.function.SerializableConsumer) to ensure proper ordering.
      Parameters:
      entry - the entry to add, not null
      Returns:
      an execution registration that can be used to cancel the execution
    • setEnabled

      public void setEnabled(boolean enabled)
      Enables/disables the node.
      Parameters:
      enabled - a new enabled state
    • isEnabled

      public boolean isEnabled()
      Returns enabled state respecting ascendants state.

      The node may be explicitly disabled via its setEnabled(boolean) method (with false argument value). Also it may be implicitly disabled if its ascendant is explicitly disabled. The method returns the state which may be either explicit or implicit.

      The method isEnabledSelf() returns only explicit enabled state of the node.

      Returns:
      enabled state respecting ascendants state
      See Also:
    • isEnabledSelf

      public boolean isEnabledSelf()
      Returns the enabled state only for this node.

      The node may be implicitly or explicitly disabled (see isEnabled() method). This method doesn't respect ascendants enabled state. It returns the own state for the node only.

      Returns:
      the node enabled own state
      See Also: