org.apache.nifi.components.state

Interface StateManager

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 and 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 Detail

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