- Direct Known Subclasses:
OutputBuffer
Output
enables incremental,
interruptible writing of network protocols and data formats.
Output tokens
Output tokens are modeled as primitive int
s, commonly
representing Unicode code points, or raw octets; each Output
implementation specifies the semantic type of its tokens.
Output states
Output
is always in one of four states: continue,
full, done, or error. The cont state
indicates that the stream is ready to write a single token; the full
state indicates that the stream is unable to write additional tokens at this
time, but that the stream may logically resume at some point in the future;
and the done state indicates that the stream has terminated, and
that bind
will return the output result; and the
error state indicates that the stream has terminated abnormally.
isCont()
returns true
when in the cont state;
isFull()
returns true
when in the full state;
isDone()
returns true
when in the done state; and
isError()
returns true
when in the error state.
Output results
An Output
yields a value of type T
, obtained via the
bind()
method, representing some implementation defined result of
writing the output. For example, an Output<String>
implementation
may–but is not required to–yield a String
containing all code points
written to the output.
Non-blocking behavior
Output
writers never block. An Output
that would
otherwise block writing additional output instead enters the full
state, signaling the output generator to back off producing the output, but
to remain prepared to produce additional output in the future. An
Output
enters the done state when it encounters the final enf of
its output, signaling to the output generator to stop producing.
Output settings
An output generator may alter the tokens it produces based on its
Output
's settings
. Uses include pretty printing and
styling generated output. OutputSettings
subclasses can provide
additional parameters understood by specialized output producers.
Cloning
An Output
may be cloned
to branch the token
stream in an implementation specified manner. Not all Output
implementations support cloning.
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract T
bind()
Returns the implementation-defined result of writing the output.clone()
Returns an implementation-defined branch of the token stream.Writes the code points of the developer-readableDebug
string of the givenobject
.Writes the code points of the human-readableDisplay
string of the givenobject
.static <T> Output<T>
done()
Returns anOutput
in the done state, that binds anull
result.static <T> Output<T>
done
(OutputSettings settings) Returns anOutput
in the done state, with the givensettings
.static <T> Output<T>
done
(T value) Returns anOutput
in the done state, that binds the givenvalue
.static <T> Output<T>
done
(T value, OutputSettings settings) Returns anOutput
in the done state, that binds the givenvalue
, with the givensettings
.static <T> Output<T>
Returns anOutput
in the error state, with the given outputerror
.static <T> Output<T>
error
(Throwable error, OutputSettings settings) Returns anOutput
in the error state, with the given outputerror
andsettings
.flush()
Writes any internally buffered state to the underlying output stream.Returns anOutput
equivalent to thisOutput
, but whose behavior may be altered by the given out-of-bandcondition
.static <T> Output<T>
full()
Returns anOutput
in the full state, that binds anull
result.static <T> Output<T>
full
(OutputSettings settings) Returns anOutput
in the full state, with the givensettings
.static <T> Output<T>
full
(T value) Returns anOutput
in the full state, that binds the givenvalue
.static <T> Output<T>
full
(T value, OutputSettings settings) Returns anOutput
in the full state, that binds the givenvalue
, with the givensettings
.abstract boolean
isCont()
Returnstrue
when the nextwrite(int)
will succeed.abstract boolean
isDone()
Returnstrue
when nowrite
will ever again suucced.abstract boolean
isError()
Returnstrue
when an immediatewrite
will fail due to an error with the token stream.abstract boolean
isFull()
Returnstrue
when an immediatewrite
will fail, but writes may succeed at some point in the future.abstract boolean
isPart()
Returnstrue
if this is a partialOutput
that will enter the full state when it is unable to write additional tokens.isPart
(boolean isPart) Returns a partialOutput
equivalent to thisOutput
, ifisPart
istrue
; returns a finalOutput
equivalent to thisOutput
ifisPart
isfalse
.abstract OutputSettings
settings()
Returns theOutputSettings
used to configure the behavior of output producers that write to thisOutput
.settings
(OutputSettings settings) Updates thesettings
associated with thisOutput
.trap()
Returns the output error.write
(int token) Writes a singletoken
to the stream, if thisOutput
is in the cont state.Writes the code points of the givenstring
.writeln()
Writes the code points of thesettings
'line separator
.Writes the code points of the givenstring
, followed by the code points of thesettings
'line separator
.
-
Constructor Details
-
Output
public Output()
-
-
Method Details
-
isCont
public abstract boolean isCont() -
isFull
public abstract boolean isFull()Returnstrue
when an immediatewrite
will fail, but writes may succeed at some point in the future. i.e. thisOutput
is in the full state. -
isDone
public abstract boolean isDone()Returnstrue
when nowrite
will ever again suucced. i.e. thisOutput
is in the done state. -
isError
public abstract boolean isError()Returnstrue
when an immediatewrite
will fail due to an error with the token stream. i.e. thisOutput
is in the error state. Whentrue
,trap()
will return the output error. -
isPart
public abstract boolean isPart()Returnstrue
if this is a partialOutput
that will enter the full state when it is unable to write additional tokens. -
isPart
Returns a partialOutput
equivalent to thisOutput
, ifisPart
istrue
; returns a finalOutput
equivalent to thisOutput
ifisPart
isfalse
. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
write
Writes a singletoken
to the stream, if thisOutput
is in the cont state. Returns anOutput
in the error state if thisOutput
is not in the cont state. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
write
Writes the code points of the givenstring
. Assumes this is a UnicodeOutput
with sufficient capacity. Returns anOutput
in the error state if thisOutput
exits the cont state before the fullstring
has been writtem. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
writeln
Writes the code points of the givenstring
, followed by the code points of thesettings
'line separator
. Assumes this is a UnicodeOutput
with sufficient capacity. Returns anOutput
in the error state if thisOutput
exits the cont state before the fullstring
and line separator has been written. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
writeln
Writes the code points of thesettings
'line separator
. Assumes this is a UnicodeOutput
with sufficient capacity. Returns anOutput
in the error state if thisOutput
exits the cont state before the full line separator has been written. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
display
Writes the code points of the human-readableDisplay
string of the givenobject
. Assumes this is a UnicodeOutput
with sufficient capacity. Returns anOutput
in the error state if thisOutput
exits the contt state before the full display string has been written. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
debug
Writes the code points of the developer-readableDebug
string of the givenobject
. Assumes this is a UnicodeOutput
with sufficient capacity. Returns anOutput
in the error state if thisOutput
exits the contt state before the full debug string has been written. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
flush
Writes any internally buffered state to the underlying output stream. -
fork
Returns anOutput
equivalent to thisOutput
, but whose behavior may be altered by the given out-of-bandcondition
. The caller's reference tothis
Output
should be replaced by the returnedOutput
. -
bind
Returns the implementation-defined result of writing the output. -
trap
Returns the output error. Only guaranteed to return an error when in the error state.- Throws:
OutputException
- if thisOutput
is not in the error state.
-
settings
Returns theOutputSettings
used to configure the behavior of output producers that write to thisOutput
. -
settings
Updates thesettings
associated with thisOutput
.- Returns:
this
-
clone
Returns an implementation-defined branch of the token stream.- Overrides:
clone
in classObject
- Throws:
UnsupportedOperationException
- if thisOutput
cannot be cloned.
-
full
Returns anOutput
in the full state, that binds anull
result. -
full
Returns anOutput
in the full state, with the givensettings
. -
full
Returns anOutput
in the full state, that binds the givenvalue
. -
full
Returns anOutput
in the full state, that binds the givenvalue
, with the givensettings
. -
done
Returns anOutput
in the done state, that binds anull
result. -
done
Returns anOutput
in the done state, with the givensettings
. -
done
Returns anOutput
in the done state, that binds the givenvalue
. -
done
Returns anOutput
in the done state, that binds the givenvalue
, with the givensettings
. -
error
Returns anOutput
in the error state, with the given outputerror
. -
error
Returns anOutput
in the error state, with the given outputerror
andsettings
.
-