Module swim.codec
Package swim.codec

Class 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:
    OutputSettings, Writer
    • Constructor Summary

      Constructors 
      Constructor Description
      Output()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      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.
    • Constructor Detail

      • Output

        public Output()
    • Method Detail

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