Module org.apache.nifi
Package org.apache.nifi.components.state

Interface StateManager

All Known Implementing Classes:
NopStateManager
public interface StateManager

The StateManager is responsible for providing NiFi components a mechanism for storing and retrieving state.

When calling methods in this class, the Scope is used in order to specify whether state should be stored/retrieved from the local state or the clustered state. However, if any instance of NiFi is not clustered (or is disconnected from its cluster), the Scope is not really relevant and the local state will be used. This allows component developers to not concern themselves with whether or not a particular instance of NiFi is clustered. Instead, developers should assume that the instance is indeed clustered and write the component accordingly. If not clustered, the component will still behave in the same manner, as a standalone node could be thought of as a "cluster of 1."

This mechanism is designed to allow developers to easily store and retrieve small amounts of state. The storage mechanism is implementation-specific, but is typically either stored on a remote system or on disk. For that reason, one should consider the cost of storing and retrieving this data, and the amount of data should be kept to the minimum required.

Any component that wishes to use the StateManager should also use the Stateful annotation to provide a description of what state is being stored and what Scope is used. If this annotation is not present, the UI will not expose such information or allow DFMs to clear the state.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear(Scope scope)
    Clears all keys and values from the component's state
    StateMap
    getState(Scope scope)
    Returns the current state for the component.
    boolean
    replace(StateMap oldValue, Map<String,String> newValue, Scope scope)
    Updates the value of the component's state to the new value if and only if the value currently is the same as the given oldValue.
    void
    setState(Map<String,String> state, Scope scope)
    Updates the value of the component's state, setting it to given value

  • Method Details

    • setState

      void setState(Map<String,String> state, Scope scope) throws IOException
      Updates the value of the component's state, setting it to given value
      Parameters:
      state - the value to change the state to
      scope - the scope to use when storing the state
      Throws:
      StateTooLargeException - if attempting to store more state than is allowed by the backing storage mechanism
      IOException - if unable to communicate with the underlying storage mechanism

    • getState

      StateMap getState(Scope scope) throws IOException
      Returns the current state for the component. This return value will never be null. If the state has not yet been set, the StateMap's version will be -1, and the map of values will be empty.
      Parameters:
      scope - the scope to use when fetching the state
      Returns:
      the current state for the component
      Throws:
      IOException - if unable to communicate with the underlying storage mechanism

    • replace

      boolean replace(StateMap oldValue, Map<String,String> newValue, Scope scope) throws IOException
      Updates the value of the component's state to the new value if and only if the value currently is the same as the given oldValue.
      Parameters:
      oldValue - the old value to compare against
      newValue - the new value to use if and only if the state's value is the same as the given oldValue
      scope - the scope to use for storing the new state
      Returns:
      true if the state was updated to the new value, false if the state's value was not equal to oldValue
      Throws:
      StateTooLargeException - if attempting to store more state than is allowed by the backing storage mechanism
      IOException - if unable to communicate with the underlying storage mechanism

    • clear

      void clear(Scope scope) throws IOException
      Clears all keys and values from the component's state
      Parameters:
      scope - the scope whose values should be cleared
      Throws:
      IOException - if unable to communicate with the underlying storage mechanism