IFrameWriter is the interface implemented by a stream consumer. An
IFrameWriter could be in one of
the following states:
- INITIAL
- OPENED
- CLOSED
- FAILED
A producer follows the following protocol when using an
IFrameWriter.
Initially, the
IFrameWriter is in the INITIAL state.
The first valid call to an
IFrameWriter is always the
IFrameWriter#open(). This call provides the
opportunity for the
IFrameWriter implementation to allocate any resources for its
processing. Once open() is called, no matter successfully or not, the
IFrameWriter is in the OPENED
state.
While the
IFrameWriter is in the OPENED state, the producer can call one of:
-
IFrameWriter#close() to give up any resources owned by the
IFrameWriter and enter the CLOSED
state.
-
IFrameWriter#nextFrame(ByteBuffer) to provide data to the
IFrameWriter. The call returns normally
on success and the
IFrameWriter remains in the OPENED state. On failure, the call throws a
HyracksDataException, the
IFrameWriter remains in the OPENED state.
-
IFrameWriter#flush() to push tuples that are ready in the output frame. The
IFrameWriter remains
in the OPENED state.
-
IFrameWriter#fail() to indicate that stream is to be aborted. The
IFrameWriter enters the FAILED
state.
In the FAILED state, the only call allowed is the
IFrameWriter#close() to move the
IFrameWriter into
the CLOSED
state and give up all resources.
No calls are allowed when the
IFrameWriter is in the CLOSED state.
Note: If the call to
IFrameWriter#open() failed, the
IFrameWriter#close() must still be called by the
producer.