Module swim.codec

Package swim.codec

Class Encoder<I,O>

java.lang.Object

swim.codec.Encoder<I,O>

Direct Known Subclasses:

Deflate, DynamicEncoder, Writer

public abstract class Encoder<I,O>
extends Object

Continuation of how encode subsequent output buffers for a byte stream. 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

Constructor	Description
Encoder()

Method Summary

Modifier and Type	Method	Description
<O2> Encoder<I,O2>	andThen(Encoder<I,O2> that)	Returns an Encoder that continues encoding that Encoder, after it finishes encoding this Encoder.
<I2> Encoder<I2,O>	asDone()	Casts a done Encoder to a different input type.
<I2, O2> Encoder<I2,O2>	asError()	Casts an errored Encoder to different input and output types.
O	bind()	Returns the encoded result.
static <I, O> Encoder<I,O>	done()	Returns an Encoder in the done state that binds a null encoded result.
static <I, O> Encoder<I,O>	done(O output)	Returns an Encoder in the done state that binds the given encoded output.
static <I, O> Encoder<I,O>	error(Throwable error)	Returns an Encoder in the error state that traps the given encode error.
Encoder<I,O>	feed(I input)	Returns an Encoder that represents the continuation of how to encode the given input object.
Encoder<I,O>	fork(Object condition)	Returns an Encoder continuation whose behavior may be altered by the given out-of-band condition.
boolean	isCont()	Returns true when pull is able to produce buffer data.
boolean	isDone()	Returns true when encoding has terminated successfully, and bind will return the encoded result.
boolean	isError()	Returns true when encoding has terminated in failure, and trap will return the encode error.
abstract Encoder<I,O>	pull(OutputBuffer<?> output)	Incrementally encodes as much output buffer data as possible, and returns another Encoder that represents the continuation of how to write additional buffer data.
Throwable	trap()	Returns the encode error.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Encoder

public Encoder()

Method Details

isCont

public boolean isCont()

Returns true when pull is able to produce buffer data. i.e. this Encoder is in the cont state.

isDone

public boolean isDone()

Returns true when encoding has terminated successfully, and bind will return the encoded result. i.e. this Encoder is in the done state.

isError

public boolean isError()

Returns true when encoding has terminated in failure, and trap will return the encode error. i.e. this Encoder is in the error state.

feed

public Encoder<I,O> feed(I input)

Returns an Encoder that represents the continuation of how to encode the given input object.

Throws:

IllegalArgumentException - if this Encoder does not know how to encode the given input object.

pull

public abstract Encoder<I,O> pull(OutputBuffer<?> output)

Incrementally encodes as much output buffer data as possible, and returns another Encoder that represents the continuation of how to write additional buffer data. If isLast is true, then pull must return a terminated Encoder, i.e. an Encoder in the done state, or in the error state. The given output buffer is only guaranteed to be valid for the duration of the method call; references to output must not be stored.

fork

public Encoder<I,O> fork(Object condition)

Returns an Encoder continuation whose behavior may be altered by the given out-of-band condition.

bind

public O bind()

Returns the encoded result. Only guaranteed to return a result when in the done state.

Throws:

IllegalStateException - if this Encoder is not in the done state.

trap

public Throwable trap()

Returns the encode error. Only guaranteed to return an error when in the error state.

Throws:

IllegalStateException - if this Encoder is not in the error state.

asDone

public <I2> Encoder<I2,O> asDone()

Casts a done Encoder to a different input type. An Encoder in the done state can have any input type.

Throws:

IllegalStateException - if this Encoder is not in the done state.

asError

public <I2,
O2> Encoder<I2,O2> asError()

Casts an errored Encoder to different input and output types. An Encoder in the error state can have any input type, and any output type.

Throws:

IllegalStateException - if this Encoder is not in the error state.

andThen

public <O2> Encoder<I,O2> andThen(Encoder<I,O2> that)

Returns an Encoder that continues encoding that Encoder, after it finishes encoding this Encoder.

done

public static <I,
O> Encoder<I,O> done()

Returns an Encoder in the done state that binds a null encoded result.

done

public static <I,
O> Encoder<I,O> done(O output)

Returns an Encoder in the done state that binds the given encoded output.

error

public static <I,
O> Encoder<I,O> error(Throwable error)

Returns an Encoder in the error state that traps the given encode error.