Module swim.codec
Package swim.codec

Class Output<T>

java.lang.Object
swim.codec.Output<T>
Direct Known Subclasses:
OutputBuffer
public abstract class Output<T> extends Object
Non-blocking token stream writer. Output enables incremental, interruptible writing of network protocols and data formats.

Output tokens

Output tokens are modeled as primitive ints, commonly representing Unicode code points, or raw octets; each Output implementation specifies the semantic type of its tokens.

Output states

Output is always in one of four states: continue, full, done, or error. The cont state indicates that the stream is ready to write a single token; the full state indicates that the stream is unable to write additional tokens at this time, but that the stream may logically resume at some point in the future; and the done state indicates that the stream has terminated, and that bind will return the output result; and the error state indicates that the stream has terminated abnormally. isCont() returns true when in the cont state; isFull() returns true when in the full state; isDone() returns true when in the done state; and isError() returns true when in the error state.

Output results

An Output yields a value of type T, obtained via the bind() method, representing some implementation defined result of writing the output. For example, an Output<String> implementation may–but is not required to–yield a String containing all code points written to the output.

Non-blocking behavior

Output writers never block. An Output that would otherwise block writing additional output instead enters the full state, signaling the output generator to back off producing the output, but to remain prepared to produce additional output in the future. An Output enters the done state when it encounters the final enf of its output, signaling to the output generator to stop producing.

Output settings

An output generator may alter the tokens it produces based on its Output's settings. Uses include pretty printing and styling generated output. OutputSettings subclasses can provide additional parameters understood by specialized output producers.

Cloning

An Output may be cloned to branch the token stream in an implementation specified manner. Not all Output implementations support cloning.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Output()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract T
    bind()
    Returns the implementation-defined result of writing the output.
    Output<T>
    clone()
    Returns an implementation-defined branch of the token stream.
    Output<T>
    debug(Object object)
    Writes the code points of the developer-readable Debug string of the given object.
    Output<T>
    display(Object object)
    Writes the code points of the human-readable Display string of the given object.
    static <T> Output<T>
    done()
    Returns an Output in the done state, that binds a null result.
    static <T> Output<T>
    done(OutputSettings settings)
    Returns an Output in the done state, with the given settings.
    static <T> Output<T>
    done(T value)
    Returns an Output in the done state, that binds the given value.
    static <T> Output<T>
    done(T value, OutputSettings settings)
    Returns an Output in the done state, that binds the given value, with the given settings.
    static <T> Output<T>
    error(Throwable error)
    Returns an Output in the error state, with the given output error.
    static <T> Output<T>
    error(Throwable error, OutputSettings settings)
    Returns an Output in the error state, with the given output error and settings.
    Output<T>
    flush()
    Writes any internally buffered state to the underlying output stream.
    Output<T>
    fork(Object condition)
    Returns an Output equivalent to this Output, but whose behavior may be altered by the given out-of-band condition.
    static <T> Output<T>
    full()
    Returns an Output in the full state, that binds a null result.
    static <T> Output<T>
    full(OutputSettings settings)
    Returns an Output in the full state, with the given settings.
    static <T> Output<T>
    full(T value)
    Returns an Output in the full state, that binds the given value.
    static <T> Output<T>
    full(T value, OutputSettings settings)
    Returns an Output in the full state, that binds the given value, with the given settings.
    abstract boolean
    isCont()
    Returns true when the next write(int) will succeed.
    abstract boolean
    isDone()
    Returns true when no write will ever again suucced.
    abstract boolean
    isError()
    Returns true when an immediate write will fail due to an error with the token stream.
    abstract boolean
    isFull()
    Returns true when an immediate write will fail, but writes may succeed at some point in the future.
    abstract boolean
    isPart()
    Returns true if this is a partial Output that will enter the full state when it is unable to write additional tokens.
    abstract Output<T>
    isPart(boolean isPart)
    Returns a partial Output equivalent to this Output, if isPart is true; returns a final Output equivalent to this Output if isPart is false.
    abstract OutputSettings
    settings()
    Returns the OutputSettings used to configure the behavior of output producers that write to this Output.
    abstract Output<T>
    settings(OutputSettings settings)
    Updates the settings associated with this Output.
    Throwable
    trap()
    Returns the output error.
    abstract Output<T>
    write(int token)
    Writes a single token to the stream, if this Output is in the cont state.
    Output<T>
    write(String string)
    Writes the code points of the given string.
    Output<T>
    writeln()
    Writes the code points of the settings' line separator.
    Output<T>
    writeln(String string)
    Writes the code points of the given string, followed by the code points of the settings' line separator.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Output

      public Output()

  • Method Details

    • isCont

      public abstract boolean isCont()
      Returns true when the next write(int) will succeed. i.e. this Output is in the cont state.

    • isFull

      public abstract boolean isFull()
      Returns true when an immediate write will fail, but writes may succeed at some point in the future. i.e. this Output is in the full state.

    • isDone

      public abstract boolean isDone()
      Returns true when no write will ever again suucced. i.e. this Output is in the done state.

    • isError

      public abstract boolean isError()
      Returns true when an immediate write will fail due to an error with the token stream. i.e. this Output is in the error state. When true, trap() will return the output error.

    • isPart

      public abstract boolean isPart()
      Returns true if this is a partial Output that will enter the full state when it is unable to write additional tokens.

    • isPart

      public abstract Output<T> isPart(boolean isPart)
      Returns a partial Output equivalent to this Output, if isPart is true; returns a final Output equivalent to this Output if isPart is false. The caller's reference to this Output should be replaced by the returned Output.

    • write

      public abstract Output<T> write(int token)
      Writes a single token to the stream, if this Output is in the cont state. Returns an Output in the error state if this Output is not in the cont state. The caller's reference to this Output should be replaced by the returned Output.

    • write

      public Output<T> write(String string)
      Writes the code points of the given string. Assumes this is a Unicode Output with sufficient capacity. Returns an Output in the error state if this Output exits the cont state before the full string has been writtem. The caller's reference to this Output should be replaced by the returned Output.

    • writeln

      public Output<T> writeln(String string)
      Writes the code points of the given string, followed by the code points of the settings' line separator. Assumes this is a Unicode Output with sufficient capacity. Returns an Output in the error state if this Output exits the cont state before the full string and line separator has been written. The caller's reference to this Output should be replaced by the returned Output.

    • writeln

      public Output<T> writeln()
      Writes the code points of the settings' line separator. Assumes this is a Unicode Output with sufficient capacity. Returns an Output in the error state if this Output exits the cont state before the full line separator has been written. The caller's reference to this Output should be replaced by the returned Output.

    • display

      public Output<T> display(Object object)
      Writes the code points of the human-readable Display string of the given object. Assumes this is a Unicode Output with sufficient capacity. Returns an Output in the error state if this Output exits the contt state before the full display string has been written. The caller's reference to this Output should be replaced by the returned Output.

    • debug

      public Output<T> debug(Object object)
      Writes the code points of the developer-readable Debug string of the given object. Assumes this is a Unicode Output with sufficient capacity. Returns an Output in the error state if this Output exits the contt state before the full debug string has been written. The caller's reference to this Output should be replaced by the returned Output.

    • flush

      public Output<T> flush()
      Writes any internally buffered state to the underlying output stream.

    • fork

      public Output<T> fork(Object condition)
      Returns an Output equivalent to this Output, but whose behavior may be altered by the given out-of-band condition. The caller's reference to this Output should be replaced by the returned Output.

    • bind

      public abstract T bind()
      Returns the implementation-defined result of writing the output.

    • trap

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

    • settings

      public abstract OutputSettings settings()
      Returns the OutputSettings used to configure the behavior of output producers that write to this Output.

    • settings

      public abstract Output<T> settings(OutputSettings settings)
      Updates the settings associated with this Output.
      Returns:
      this

    • clone

      public Output<T> clone()
      Returns an implementation-defined branch of the token stream.
      Overrides:
      clone in class Object
      Throws:
      UnsupportedOperationException - if this Output cannot be cloned.

    • full

      public static <T> Output<T> full()
      Returns an Output in the full state, that binds a null result.

    • full

      public static <T> Output<T> full(OutputSettings settings)
      Returns an Output in the full state, with the given settings.

    • full

      public static <T> Output<T> full(T value)
      Returns an Output in the full state, that binds the given value.

    • full

      public static <T> Output<T> full(T value, OutputSettings settings)
      Returns an Output in the full state, that binds the given value, with the given settings.

    • done

      public static <T> Output<T> done()
      Returns an Output in the done state, that binds a null result.

    • done

      public static <T> Output<T> done(OutputSettings settings)
      Returns an Output in the done state, with the given settings.

    • done

      public static <T> Output<T> done(T value)
      Returns an Output in the done state, that binds the given value.

    • done

      public static <T> Output<T> done(T value, OutputSettings settings)
      Returns an Output in the done state, that binds the given value, with the given settings.

    • error

      public static <T> Output<T> error(Throwable error)
      Returns an Output in the error state, with the given output error.

    • error

      public static <T> Output<T> error(Throwable error, OutputSettings settings)
      Returns an Output in the error state, with the given output error and settings.