Module swim.codec
Package swim.codec

Class Writer<I,​O>


  • public abstract class Writer<I,​O>
    extends Encoder<I,​O>
    Continuation of how to write subsequent Output tokens to a stream. Writer enables efficient, interruptible writing of network protocols and data formats, without intermediate buffering.

    Output tokens

    A Writer writes tokens to an Output writer. Output tokens are modeled as primitive ints, commonly representing Unicode code points, or raw octets. Each Writer implementation specifies the semantic type of output tokens it produces.

    Writer states

    A Writer is always in one of three states: continue, done, or error. The cont state indicates that pull is ready to produce Output; the done state indicates that writing terminated successfully, and that bind will return the written result; the error state indicates that writing terminated in failure, and that trap will return the write error. Writer subclasses default to the cont state.

    Feeding input

    The feed(I) method returns a Writer that represents the continuation of how to write the given input object to subsequent Output writers. feed can be used to specify an initial object to write, or to change the object to be written.

    Pulling output

    The pull(Output) method incrementally writes as much Output as it can, before returning another Writer that represents the continuation of how to write additional Output. The Output passed to pull is only guaranteed to be valid for the duration of the method call; references to the provided Output instance must not be stored.

    Writer results

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

    Continuations

    A Writer instance represents a continuation of how to write remaining Output. Rather than writing a complete output in one go, a Writer takes an Output chunk and returns another Writer instance that knows how to write subsequent Output chunks. This enables non-blocking, incremental writing that can be interrupted whenever an Output writer runs out of space. A Writer terminates by returning a continuation in either the done state, or the error state. done(Object) returns a Writer in the done state. error(Throwable) returns a Writer in the error state.

    Forking

    The fork(Object) method passes an out-of-band condition to a Writer, yielding a Writer continuation whose behavior may be altered by the given condition. For example, a console Writer might support a fork condition that changes the color and style of printed text. The types of conditions accepted by fork, and their intended semantics, are implementation defined.

    • Constructor Summary

      Constructors 
      Constructor Description
      Writer()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      <O2> Writer<I,​O2> andThen​(Encoder<I,​O2> that)
      Returns an Encoder that continues encoding that Encoder, after it finishes encoding this Encoder.
      <O2> Writer<I,​O2> andThen​(Writer<I,​O2> that)
      Returns a Writer that continues writing that Writer, after it finishes writing this Writer.
      <I2> Writer<I2,​O> asDone()
      Casts a done Writer to a different input type.
      <I2,​O2>
      Writer<I2,​O2>
      asError()
      Casts an errored Writer to different input and output types.
      O bind()
      Returns the written result.
      static <I,​O>
      Writer<I,​O>
      done()
      Returns a Writer in the done state that binds a null written result.
      static <I,​O>
      Writer<I,​O>
      done​(O output)
      Returns a Writer in the done state that binds the given written output.
      static <I,​O>
      Writer<I,​O>
      error​(Throwable error)
      Returns a Writer in the error state that traps the given write error.
      Writer<I,​O> feed​(I input)
      Returns a Writer that represents the continuation of how to write the given input object.
      Writer<I,​O> fork​(Object condition)
      Returns a Writer continuation whose behavior may be altered by the given out-of-band condition.
      boolean isCont()
      Returns true when pull is able to produce Output.
      boolean isDone()
      Returns true when writing has terminated successfully, and bind will return the written result.
      boolean isError()
      Returns true when writing has terminated in failure, and trap will return the write error.
      abstract Writer<I,​O> pull​(Output<?> output)
      Incrementally writes as much output as possible, and returns another Writer that represents the continuation of how to write additional Output.
      Writer<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 write error.
    • Constructor Detail

      • Writer

        public Writer()
    • Method Detail

      • isCont

        public boolean isCont()
        Returns true when pull is able to produce Output. i.e. this Writer is in the cont state.
        Overrides:
        isCont in class Encoder<I,​O>
      • isDone

        public boolean isDone()
        Returns true when writing has terminated successfully, and bind will return the written result. i.e. this Writer is in the done state.
        Overrides:
        isDone in class Encoder<I,​O>
      • isError

        public boolean isError()
        Returns true when writing has terminated in failure, and trap will return the write error. i.e. this Writer is in the error state.
        Overrides:
        isError in class Encoder<I,​O>
      • feed

        public Writer<I,​O> feed​(I input)
        Returns a Writer that represents the continuation of how to write the given input object.
        Overrides:
        feed in class Encoder<I,​O>
        Throws:
        IllegalArgumentException - if this Writer does not know how to write the given input object.
      • pull

        public abstract Writer<I,​O> pull​(Output<?> output)
        Incrementally writes as much output as possible, and returns another Writer that represents the continuation of how to write additional Output. If output enters the done state, pull must return a terminated Writer, i.e. a Writer in the done state, or in the error state. The given output is only guaranteed to be valid for the duration of the method call; references to output must not be stored.
      • pull

        public Writer<I,​O> pull​(OutputBuffer<?> output)
        Description copied from class: Encoder
        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.
        Specified by:
        pull in class Encoder<I,​O>
      • fork

        public Writer<I,​O> fork​(Object condition)
        Returns a Writer continuation whose behavior may be altered by the given out-of-band condition.
        Overrides:
        fork in class Encoder<I,​O>
      • bind

        public O bind()
        Returns the written result. Only guaranteed to return a result when in the done state.
        Overrides:
        bind in class Encoder<I,​O>
        Throws:
        IllegalStateException - if this Writer is not in the done state.
      • trap

        public Throwable trap()
        Returns the write error. Only guaranteed to return an error when in the error state.
        Overrides:
        trap in class Encoder<I,​O>
        Throws:
        IllegalStateException - if this Writer is not in the error state.
      • asDone

        public <I2> Writer<I2,​O> asDone()
        Casts a done Writer to a different input type. A Writer in the done state can have any input type.
        Overrides:
        asDone in class Encoder<I,​O>
        Throws:
        IllegalStateException - if this Writer is not in the done state.
      • asError

        public <I2,​O2> Writer<I2,​O2> asError()
        Casts an errored Writer to different input and output types. A Writer in the error state can have any input type, and any output type.
        Overrides:
        asError in class Encoder<I,​O>
        Throws:
        IllegalStateException - if this Writer is not in the error state.
      • andThen

        public <O2> Writer<I,​O2> andThen​(Writer<I,​O2> that)
        Returns a Writer that continues writing that Writer, after it finishes writing this Writer.
      • andThen

        public <O2> Writer<I,​O2> andThen​(Encoder<I,​O2> that)
        Description copied from class: Encoder
        Returns an Encoder that continues encoding that Encoder, after it finishes encoding this Encoder.
        Overrides:
        andThen in class Encoder<I,​O>
      • done

        public static <I,​O> Writer<I,​O> done()
        Returns a Writer in the done state that binds a null written result.
      • done

        public static <I,​O> Writer<I,​O> done​(O output)
        Returns a Writer in the done state that binds the given written output.
      • error

        public static <I,​O> Writer<I,​O> error​(Throwable error)
        Returns a Writer in the error state that traps the given write error.