Module swim.codec
Package swim.codec

Class 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()  

    • Constructor Detail

      • Decoder

        public Decoder()

    • Method Detail

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

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