Module swim.codec
Package swim.codec

Class Decoder<O>

java.lang.Object
swim.codec.Decoder<O>
Direct Known Subclasses:
DynamicDecoder, Inflate, Parser
public abstract class Decoder<O> extends Object
Continuation of how to decode subsequent input buffers from a byte stream. Decoder enables efficient, interruptible decoding of network protocols and data formats, without intermediate buffer copying.

Decoder states

A Decoder is always in one of three states: continue, done, or error. The cont state indicates that feed is ready to consume input buffer data; the done state indicates that decoding terminated successfully, and that bind will return the decoded result; the error state indicates that decoding terminated in failure, and that trap will return the decode error. Decoder subclasses default to the cont state.

Feeding input

The feed(InputBuffer) method incrementally decodes as much InputBuffer data as it can, before returning another Decoder that represents the continuation of how to decode additional InputBuffer data. The InputBuffer passed to feed is only guaranteed to be valid for the duration of the method call; references to the provided InputBuffer instance must not be stored.

Decoder results

A Decoder produces a decoded 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 Decoder provides a decode error via the trap() method. trap is only guaranteed to return an error when in the error state.

Continuations

A Decoder instance represents a continuation of how to decode remaining InputBuffer data. Rather than parsing a completely buffered input in one go, a Decoder takes a buffered chunk and returns another Decoder instance that knows how to decode subsequent buffered chunks. This enables non-blocking, incremental decoding that can be interrupted whenever an InputBuffer runs out of immediately available data. A Decoder terminates by returning a continuation in either the done state, or the error state. done(Object) returns a Decoder in the done state. error(Throwable) returns a Decoder in the error state.

Immutability

A Decoder should be immutable. Specifically, an invocation of feed should not alter the behavior of future calls to feed on the same Decoder instance. A Decoder should only mutate its internal state if it's essential to do so, such as for critical path performance reasons.

Forking

The fork(Object) method passes an out-of-band condition to a Decoder, yielding a Decoder continuation whose behavior may be altered by the given condition. For example, a text Decoder 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
    Decoder()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    <O> Decoder<O>
    asError()
    Casts an errored Decoder to a different output type.
    O
    bind()
    Returns the decoded result.
    static <O> Decoder<O>
    done()
    Returns a Decoder in the done state that binds a null decoded result.
    static <O> Decoder<O>
    done(O output)
    Returns a Decoder in the done state that binds the given decoded output.
    static <O> Decoder<O>
    error(Throwable error)
    Returns a Decoder in the error state that traps the given decode error.
    abstract Decoder<O>
    feed(InputBuffer input)
    Incrementally decodes as much input buffer data as possible, and returns another Decoder that represents the continuation of how to decode additional buffer data.
    Decoder<O>
    fork(Object condition)
    Returns a Decoder continuation whose behavior may be altered by the given out-of-band condition.
    boolean
    isCont()
    Returns true when feed is able to consume InputBuffer data.
    boolean
    isDone()
    Returns true when decoding has terminated successfully, and bind will return the decoded result.
    boolean
    isError()
    Returns true when decoding has terminated in failure, and trap will return the decode error.
    Throwable
    trap()
    Returns the decode error.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Decoder

      public Decoder()

  • Method Details

    • isCont

      public boolean isCont()
      Returns true when feed is able to consume InputBuffer data. i.e. this Decoder is in the cont state.

    • isDone

      public boolean isDone()
      Returns true when decoding has terminated successfully, and bind will return the decoded result. i.e. this Decoder is in the done state.

    • isError

      public boolean isError()
      Returns true when decoding has terminated in failure, and trap will return the decode error. i.e. this Decoder is in the error state.

    • feed

      public abstract Decoder<O> feed(InputBuffer input)
      Incrementally decodes as much input buffer data as possible, and returns another Decoder that represents the continuation of how to decode additional buffer data. If isLast is true, then feed must return a terminated Decoder, i.e. a Decoder in the done state, or in the error state. The given input buffer is only guaranteed to be valid for the duration of the method call; references to input must not be stored.

    • fork

      public Decoder<O> fork(Object condition)
      Returns a Decoder continuation whose behavior may be altered by the given out-of-band condition.

    • bind

      public O bind()
      Returns the decoded result. Only guaranteed to return a result when in the done state.
      Throws:
      IllegalStateException - if this Decoder is not in the done state.

    • trap

      public Throwable trap()
      Returns the decode error. Only guaranteed to return an error when in the error state.
      Throws:
      IllegalStateException - if this Decoder is not in the error state.

    • asError

      public <O> Decoder<O> asError()
      Casts an errored Decoder to a different output type. A Decoder in the error state can have any output type.
      Throws:
      IllegalStateException - if this Decoder is not in the error state.

    • done

      public static <O> Decoder<O> done()
      Returns a Decoder in the done state that binds a null decoded result.

    • done

      public static <O> Decoder<O> done(O output)
      Returns a Decoder in the done state that binds the given decoded output.

    • error

      public static <O> Decoder<O> error(Throwable error)
      Returns a Decoder in the error state that traps the given decode error.