com.ibm.streams.operator.state

Interface StateHandler

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

All Known Implementing Classes:

DelegateStateHandler, OrderedStateHandlers, SortedTupleWindow, StatefulWindowListener, TumblingWindowSort

public interface StateHandler
extends java.io.Closeable

Handler for operator state. If an Operator is an instance of StateHandler then it is automatically registered as a state handler, otherwise an operator registers an instance of this interface using OperatorContext.registerStateHandler(StateHandler).
Operators that need to manage state are encouraged to always utilize a StateHandler either by implementing StateHandler or registering a state handler.

The SPL Runtime invokes StateHandler methods when:

• checkpointing is enabled.
• the operator is in a consistent region.

StateHandler implementations should be careful to honor the contract of this interface to allow use in future scenarios. For example, no assumptions should be made about the operator being in a consistent region or checkpointing, and tuple submission should only occur from drain().

When periodic checkpointing is enabled the SPL Runtime will call checkpoint(Checkpoint) for each registered state handler at the configured period.
With operator driven checkpointing the operator calls CheckpointContext.createCheckpoint() to create a checkpoint, that will result in a callback to checkpoint(Checkpoint) for all registered handlers. These callbacks occur on the thread that called createCheckpoint().
After PE restart, the SPL Runtime will reset the operator to a consistent state by calling reset(Checkpoint) or resetToInitialState().

In a consistent region a operator drains it processing and persists it state for the cut point defined by the establishing operator. The SPL runtime calls drain() and checkpoint(Checkpoint) at the correct times to ensure all operators in a region drain their processing and persist their state, consistent with having seen all tuples and marks up to the point defined by the establishing operator.
An operator becomes consistent with this sequence:

1. The operator has processed all tuples and marks on any data (non-control) input ports in the region.
2. Draining operator processing using drain() for all state handlers.
3. The operator has processed all tuples and marks on any control input ports in the region.
4. Persisting state using checkpoint(Checkpoint) for all state handlers.

Note that each of these steps is optional, for example a stateless operator may only perform step 2 to drain processing.
After a failure in the region, the SPL Runtime will reset the operator to a consistent state by calling reset(Checkpoint) or resetToInitialState().

Since:

InfoSphere® Streams Version 4.0

Method Summary

Methods

Modifier and Type	Method and Description
void	checkpoint(Checkpoint checkpoint) Checkpoint the operator state to support resetting of its state to the saved state, using reset(Checkpoint).
void	drain() Drain any outstanding processing.
void	reset(Checkpoint checkpoint) Reset the operator to a previous state defined by checkpoint.
void	resetToInitialState() Reset the operator to its initial state.
void	retireCheckpoint(long id) Called when a checkpoint can be retired.

Methods inherited from interface java.io.Closeable

close

Method Detail

drain

void drain()
           throws java.lang.Exception

Drain any outstanding processing. Once this method returns, the operator is indicating that it has drained all outstanding processing for all input ports.
The method may:

• Submit tuples to output ports.
• Interact with external systems
• Wait for background activity to drain outstanding work

For a consistent region:

• This method is called once all tuples and marks for the current cut for all data (non-control) input ports in the region have been processed, meaning the process and processPunctuation have returned for all tuples and marks.
• A permit is implicitly acquired before the method is called, and released once it returns.
• This method is not called concurrently with tuple or mark processing for any data (non-control) input ports in the region.
• This method is may be called concurrently with tuple or mark or mark processing for any autonomous input ports

Throws:

java.lang.Exception - Exception attempting to drain state.

reset

void reset(Checkpoint checkpoint)
           throws java.lang.Exception

Reset the operator to a previous state defined by checkpoint.

When in a consistent region checkpoint corresponds to the a previous successful drain and checkpoint cut cycle for the entire region. state.

Throws:

java.lang.Exception - Exception attempting to reset state.

checkpoint

void checkpoint(Checkpoint checkpoint)
                throws java.lang.Exception

Checkpoint the operator state to support resetting of its state to the saved state, using reset(Checkpoint).

For a consistent region this method is called when:

• drain() has completed
• All background threads have released processing permits.
• All control input ports (if any) have been drained.

Throws:

java.lang.Exception - Exception attempting to checkpoint state.

retireCheckpoint

void retireCheckpoint(long id)
                      throws java.lang.Exception

Called when a checkpoint can be retired.

Parameters:

id - Id of checkpoint.

Throws:

java.lang.Exception - Exception attempting to retire a checkpoint state.

resetToInitialState

void resetToInitialState()
                         throws java.lang.Exception

Reset the operator to its initial state.

If the operator is in a consistent region then this is called if a reset occurs prior to the first successful completion of drain and checkpoint cycle for the region.
This method is not called when the operator first initializes.

Throws:

java.lang.Exception - Exception attempting to retire a checkpoint state.