Module swim.codec
Package swim.codec

Class Writer<I,O>

java.lang.Object
swim.codec.Encoder<I,O>
swim.codec.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

    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.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Writer

      public Writer()

  • Method Details

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