Output
tokens to a stream.
Writer
enables efficient, interruptible writing of network protocols
and data formats, without intermediate buffering.
Output tokens
A Writer
writes tokens to an Output
writer. Output
tokens are modeled as primitive int
s, commonly representing Unicode
code points, or raw octets. Each Writer
implementation specifies
the semantic type of output tokens it produces.
Writer states
A Writer
is always in one of three states: continue,
done, or error. The cont state indicates that
pull
is ready to produce Output
; the
done state indicates that writing terminated successfully, and that
bind
will return the written result; the error
state indicates that writing terminated in failure, and that trap
will return the write error. Writer
subclasses default to the
cont state.
Feeding input
The feed(I)
method returns a Writer
that
represents the continuation of how to write the given input object to
subsequent Output
writers. feed
can be used to specify
an initial object to write, or to change the object to be written.
Pulling output
The pull(Output)
method incrementally writes as much
Output
as it can, before returning another Writer
that represents
the continuation of how to write additional Output
. The
Output
passed to pull
is only guaranteed to be valid for the
duration of the method call; references to the provided Output
instance must not be stored.
Writer results
A Writer
produces a written 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 Writer
provides a write error via the trap()
method. trap
is only
guaranteed to return an error when in the error state.
Continuations
A Writer
instance represents a continuation of how to write
remaining Output
. Rather than writing a complete output in one go,
a Writer
takes an Output
chunk and returns another
Writer
instance that knows how to write subsequent Output
chunks.
This enables non-blocking, incremental writing that can be interrupted
whenever an Output
writer runs out of space. A Writer
terminates by returning a continuation in either the done state,
or the error state. done(Object)
returns a
Writer
in the done state. error(Throwable)
returns
a Writer
in the error state.
Forking
The fork(Object)
method passes an out-of-band condition to a
Writer
, yielding a Writer
continuation whose behavior may
be altered by the given condition. For example, a console Writer
might support a fork
condition that changes the color and style of
printed text. The types of conditions accepted by fork
, and their
intended semantics, are implementation defined.
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionReturns anEncoder
that continues encodingthat
Encoder
, after it finishes encodingthis
Encoder
.Returns aWriter
that continues writingthat
Writer
, after it finishes writingthis
Writer
.asDone()
Casts a doneWriter
to a different input type.<I2,
O2> Writer<I2, O2> asError()
Casts an erroredWriter
to different input and output types.bind()
Returns the written result.static <I,
O> Writer<I, O> done()
Returns aWriter
in the done state thatbind
s anull
written result.static <I,
O> Writer<I, O> done
(O output) Returns aWriter
in the done state thatbind
s the given writtenoutput
.static <I,
O> Writer<I, O> Returns aWriter
in the error state thattrap
s the given writeerror
.Returns aWriter
that represents the continuation of how to write the giveninput
object.Returns aWriter
continuation whose behavior may be altered by the given out-of-bandcondition
.boolean
isCont()
boolean
isDone()
Returnstrue
when writing has terminated successfully, andbind
will return the written result.boolean
isError()
Returnstrue
when writing has terminated in failure, andtrap
will return the write error.Incrementally writes as muchoutput
as possible, and returns anotherWriter
that represents the continuation of how to write additionalOutput
.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 write error.
-
Constructor Details
-
Writer
public Writer()
-
-
Method Details
-
isCont
public boolean isCont() -
isDone
public boolean isDone()Returnstrue
when writing has terminated successfully, andbind
will return the written result. i.e. thisWriter
is in the done state. -
isError
public boolean isError()Returnstrue
when writing has terminated in failure, andtrap
will return the write error. i.e. thisWriter
is in the error state. -
feed
Returns aWriter
that represents the continuation of how to write the giveninput
object.- Overrides:
feed
in classEncoder<I,
O> - Throws:
IllegalArgumentException
- if thisWriter
does not know how to write the giveninput
object.
-
pull
Incrementally writes as muchoutput
as possible, and returns anotherWriter
that represents the continuation of how to write additionalOutput
. Ifoutput
enters the done state,pull
must return a terminatedWriter
, i.e. aWriter
in the done state, or in the error state. The givenoutput
is only guaranteed to be valid for the duration of the method call; references tooutput
must not be stored. -
pull
Description copied from class:Encoder
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 aWriter
continuation whose behavior may be altered by the given out-of-bandcondition
. -
bind
Returns the written result. Only guaranteed to return a result when in the done state.- Overrides:
bind
in classEncoder<I,
O> - Throws:
IllegalStateException
- if thisWriter
is not in the done state.
-
trap
Returns the write error. Only guaranteed to return an error when in the error state.- Overrides:
trap
in classEncoder<I,
O> - Throws:
IllegalStateException
- if thisWriter
is not in the error state.
-
asDone
Casts a doneWriter
to a different input type. AWriter
in the done state can have any input type.- Overrides:
asDone
in classEncoder<I,
O> - Throws:
IllegalStateException
- if thisWriter
is not in the done state.
-
asError
Casts an erroredWriter
to different input and output types. AWriter
in the error state can have any input type, and any output type.- Overrides:
asError
in classEncoder<I,
O> - Throws:
IllegalStateException
- if thisWriter
is not in the error state.
-
andThen
Returns aWriter
that continues writingthat
Writer
, after it finishes writingthis
Writer
. -
andThen
Description copied from class:Encoder
Returns anEncoder
that continues encodingthat
Encoder
, after it finishes encodingthis
Encoder
. -
done
Returns aWriter
in the done state thatbind
s anull
written result. -
done
Returns aWriter
in the done state thatbind
s the given writtenoutput
. -
error
Returns aWriter
in the error state thattrap
s the given writeerror
.
-