- Direct Known Subclasses:
Deflate
,DynamicEncoder
,Writer
Encoder
enables efficient, interruptible encoding of network
protocols and data formats, without intermediate buffer copying.
Encoder states
An Encoder
is always in one of three states: continue,
done, or error. The cont state indicates that
pull
is ready to produce buffer data; the
done state indicates that encoding terminated successfully, and that
bind
will return the encoded result; the error
state indicates that encoding terminated in failure, and that trap
will return the encode error. Encoder
subclasses default to
the cont state.
Feeding input
The feed(I)
method returns an Encoder
that
represents the continuation of how to encode the given input object to
subsequent output buffers. feed
can be used to specify an initial
object to encode, or to change the object to be encoded.
Pulling output
The pull(OutputBuffer)
method incrementally encodes as much
buffer data as it can, before returning another Encoder
that
represents the continuation of how to encoded additional buffer data.
The buffer passed to pull
is only guaranteed to be valid for the
duration of the method call; references to the provided buffer must not be
stored.
Encoder results
An Encoder
produces an encoded 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 Encoder
provides a write error via the trap()
method. trap
is only
guaranteed to return an error when in the error state.
Continuations
An Encoder
instance represents a continuation of how to encode
remaining buffer data. Rather than encoding a completely buffered output in
one go, an Encoder
takes a buffer chunk and returns another
Encoder
instance that knows how to write subsequent buffer chunks.
This enables non-blocking, incremental encoding that can be interrupted
whenever an output buffer runs out of space. An Encoder
terminates
by returning a continuation in either the done state, or the
error state. done(Object)
returns an
Encoder
in the done state. error(Throwable)
returns an Encoder
in the error state.
Forking
The fork(Object)
method passes an out-of-band condition to an
Encoder
, yielding an Encoder
continuation whose behavior may
be altered by the given condition. For example, a text Encoder
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 TypeMethodDescriptionReturns anEncoder
that continues encodingthat
Encoder
, after it finishes encodingthis
Encoder
.asDone()
Casts a doneEncoder
to a different input type.<I2,
O2> Encoder<I2, O2> asError()
Casts an erroredEncoder
to different input and output types.bind()
Returns the encoded result.static <I,
O> Encoder<I, O> done()
Returns anEncoder
in the done state thatbind
s anull
encoded result.static <I,
O> Encoder<I, O> done
(O output) Returns anEncoder
in the done state thatbind
s the given encodedoutput
.static <I,
O> Encoder<I, O> Returns anEncoder
in the error state thattrap
s the given encodeerror
.Returns anEncoder
that represents the continuation of how to encode the giveninput
object.Returns anEncoder
continuation whose behavior may be altered by the given out-of-bandcondition
.boolean
isCont()
Returnstrue
whenpull
is able to produce buffer data.boolean
isDone()
Returnstrue
when encoding has terminated successfully, andbind
will return the encoded result.boolean
isError()
Returnstrue
when encoding has terminated in failure, andtrap
will return the encode error.pull
(OutputBuffer<?> output) Incrementally encodes as muchoutput
buffer data as possible, and returns anotherEncoder
that represents the continuation of how to write additional buffer data.trap()
Returns the encode error.
-
Constructor Details
-
Encoder
public Encoder()
-
-
Method Details
-
isCont
public boolean isCont() -
isDone
public boolean isDone()Returnstrue
when encoding has terminated successfully, andbind
will return the encoded result. i.e. thisEncoder
is in the done state. -
isError
public boolean isError()Returnstrue
when encoding has terminated in failure, andtrap
will return the encode error. i.e. thisEncoder
is in the error state. -
feed
Returns anEncoder
that represents the continuation of how to encode the giveninput
object.- Throws:
IllegalArgumentException
- if thisEncoder
does not know how to encode the giveninput
object.
-
pull
Incrementally encodes as muchoutput
buffer data as possible, and returns anotherEncoder
that represents the continuation of how to write additional buffer data. IfisLast
istrue
, thenpull
must return a terminatedEncoder
, i.e. anEncoder
in the done state, or in the error state. The givenoutput
buffer is only guaranteed to be valid for the duration of the method call; references tooutput
must not be stored. -
fork
Returns anEncoder
continuation whose behavior may be altered by the given out-of-bandcondition
. -
bind
Returns the encoded result. Only guaranteed to return a result when in the done state.- Throws:
IllegalStateException
- if thisEncoder
is not in the done state.
-
trap
Returns the encode error. Only guaranteed to return an error when in the error state.- Throws:
IllegalStateException
- if thisEncoder
is not in the error state.
-
asDone
Casts a doneEncoder
to a different input type. AnEncoder
in the done state can have any input type.- Throws:
IllegalStateException
- if thisEncoder
is not in the done state.
-
asError
Casts an erroredEncoder
to different input and output types. AnEncoder
in the error state can have any input type, and any output type.- Throws:
IllegalStateException
- if thisEncoder
is not in the error state.
-
andThen
Returns anEncoder
that continues encodingthat
Encoder
, after it finishes encodingthis
Encoder
. -
done
Returns anEncoder
in the done state thatbind
s anull
encoded result. -
done
Returns anEncoder
in the done state thatbind
s the given encodedoutput
. -
error
Returns anEncoder
in the error state thattrap
s the given encodeerror
.
-