Module swim.codec
Package swim.codec

Class 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

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      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.

    • Constructor Detail

      • Encoder

        public Encoder()

    • Method Detail

      • 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.