- Direct Known Subclasses:
DynamicDecoder
,Inflate
,Parser
Decoder
enables efficient, interruptible decoding of network
protocols and data formats, without intermediate buffer copying.
Decoder states
A Decoder
is always in one of three states: continue,
done, or error. The cont state indicates that
feed
is ready to consume input buffer data; the
done state indicates that decoding terminated successfully, and that
bind
will return the decoded result; the error state
indicates that decoding terminated in failure, and that trap
will return the decode error. Decoder
subclasses default to the
cont state.
Feeding input
The feed(InputBuffer)
method incrementally decodes as much
InputBuffer
data as it can, before returning another Decoder
that represents the continuation of how to decode additional
InputBuffer
data. The InputBuffer
passed to feed
is only
guaranteed to be valid for the duration of the method call; references to
the provided InputBuffer
instance must not be stored.
Decoder results
A Decoder
produces a decoded result of type O
, obtained
via the bind()
method. bind
is only guaranteed to return
a result when in the done state; though bind
may optionally
make available partial results in other states. A failed Decoder
provides a decode error via the trap()
method. trap
is
only guaranteed to return an error when in the error state.
Continuations
A Decoder
instance represents a continuation of how to decode
remaining InputBuffer
data. Rather than parsing a completely
buffered input in one go, a Decoder
takes a buffered chunk and
returns another Decoder
instance that knows how to decode subsequent
buffered chunks. This enables non-blocking, incremental decoding that can
be interrupted whenever an InputBuffer
runs out of immediately
available data. A Decoder
terminates by returning a continuation
in either the done state, or the error state. done(Object)
returns a Decoder
in the done state.
error(Throwable)
returns a Decoder
in the
error state.
Immutability
A Decoder
should be immutable. Specifically, an invocation of
feed
should not alter the behavior of future calls to feed
on the same Decoder
instance. A Decoder
should only mutate
its internal state if it's essential to do so, such as for critical path
performance reasons.
Forking
The fork(Object)
method passes an out-of-band condition to a
Decoder
, yielding a Decoder
continuation whose behavior may
be altered by the given condition. For example, a text Decoder
might support a fork
condition to change the character encoding.
The types of conditions accepted by fork
, and their intended
semantics, are implementation defined.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription<O> Decoder<O>
asError()
Casts an erroredDecoder
to a different output type.bind()
Returns the decoded result.static <O> Decoder<O>
done()
Returns aDecoder
in the done state thatbind
s anull
decoded result.static <O> Decoder<O>
done
(O output) Returns aDecoder
in the done state thatbind
s the given decodedoutput
.static <O> Decoder<O>
Returns aDecoder
in the error state thattrap
s the given decodeerror
.feed
(InputBuffer input) Incrementally decodes as muchinput
buffer data as possible, and returns anotherDecoder
that represents the continuation of how to decode additional buffer data.Returns aDecoder
continuation whose behavior may be altered by the given out-of-bandcondition
.boolean
isCont()
boolean
isDone()
Returnstrue
when decoding has terminated successfully, andbind
will return the decoded result.boolean
isError()
Returnstrue
when decoding has terminated in failure, andtrap
will return the decode error.trap()
Returns the decode error.
-
Constructor Details
-
Decoder
public Decoder()
-
-
Method Details
-
isCont
public boolean isCont() -
isDone
public boolean isDone()Returnstrue
when decoding has terminated successfully, andbind
will return the decoded result. i.e. thisDecoder
is in the done state. -
isError
public boolean isError()Returnstrue
when decoding has terminated in failure, andtrap
will return the decode error. i.e. thisDecoder
is in the error state. -
feed
Incrementally decodes as muchinput
buffer data as possible, and returns anotherDecoder
that represents the continuation of how to decode additional buffer data. IfisLast
istrue
, thenfeed
must return a terminatedDecoder
, i.e. aDecoder
in the done state, or in the error state. The giveninput
buffer is only guaranteed to be valid for the duration of the method call; references toinput
must not be stored. -
fork
Returns aDecoder
continuation whose behavior may be altered by the given out-of-bandcondition
. -
bind
Returns the decoded result. Only guaranteed to return a result when in the done state.- Throws:
IllegalStateException
- if thisDecoder
is not in the done state.
-
trap
Returns the decode error. Only guaranteed to return an error when in the error state.- Throws:
IllegalStateException
- if thisDecoder
is not in the error state.
-
asError
Casts an erroredDecoder
to a different output type. ADecoder
in the error state can have any output type.- Throws:
IllegalStateException
- if thisDecoder
is not in the error state.
-
done
Returns aDecoder
in the done state thatbind
s anull
decoded result. -
done
Returns aDecoder
in the done state thatbind
s the given decodedoutput
. -
error
Returns aDecoder
in the error state thattrap
s the given decodeerror
.
-