Interface TaskOutput

All Superinterfaces:
AutoCloseable

public interface TaskOutput extends AutoCloseable
One of a task's two output streams - TaskExecutionContext.stdout() or TaskExecutionContext.stderr() - owned and implemented by the host.

Everything that has to happen to a byte of task output happens here, once, on the host side: it is masked against this execution's Secret mask set, streamed to the task log in chunks while the task is still running, and retained up to a bounded tail for captured(). An extension does not buffer, mask, chunk, size-limit or persist anything itself.

Two directions, one sink

Which one you use depends on who produces the bytes.
  • Something else writes them - hand asOutputStream() or asPrintStream() to whatever is producing output (such as an external command runner or streaming client).
  • You hold the source - call pipeFrom(Reader) or pipeFrom(InputStream, Charset) and let the host run the read loop: a response body, a token stream, a local file. The host reads a line at a time, so a multi-megabyte source costs a line of memory rather than its full size.
Both land in the same underlying sink, so the two forms may be mixed freely on the same TaskOutput, and stdout() and stderr() interleave in the task log in the order they were actually written.

Thread safety

Unlike the rest of TaskExecutionContext, a TaskOutput is thread-safe and may be written from a thread the extension started - which is the point, since output pumping is usually concurrent with the work producing it. Writes are serialised, so a line written from one thread never interleaves mid-line with another's.

If a writer outruns storage, writes block rather than buffering without bound or dropping lines: a release's task log is an audit record, so losing part of it silently is worse than slowing the producer down.

See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    This stream as an OutputStream, for handing to something that writes bytes.
    This stream as a PrintStream, for println-style writing.
    The tail of everything written to this stream, for storing in an output property.
    void
    Flushes anything still buffered, including a final line with no trailing newline.
    void
    pipeFrom(InputStream source, Charset charset)
    Reads source to exhaustion into this stream, decoding with charset.
    void
    pipeFrom(Reader source)
    Reads source to exhaustion into this stream, a line at a time.
  • Method Details

    • asOutputStream

      OutputStream asOutputStream()
      This stream as an OutputStream, for handing to something that writes bytes.

      Bytes are decoded as UTF-8 and split into lines by the host. The same instance is returned on every call.

    • asPrintStream

      PrintStream asPrintStream()
      This stream as a PrintStream, for println-style writing.

      A convenience wrapper over asOutputStream() with autoflush enabled and UTF-8 encoding, so a line reaches the task log without an explicit flush. The same instance is returned on every call.

    • pipeFrom

      void pipeFrom(Reader source) throws IOException
      Reads source to exhaustion into this stream, a line at a time.

      Blocks until the source is exhausted. Memory use is bounded by the longest single line, not by the total size, so this is the right way to move a large body of text into the task log. Does not close source - the caller owns it, typically in a try-with-resources.

      Parameters:
      source - the text to read; must not be null
      Throws:
      IOException - if reading source fails. A failure to write the task log does not throw - task output is best-effort and must not fail the task.
    • pipeFrom

      void pipeFrom(InputStream source, Charset charset) throws IOException
      Reads source to exhaustion into this stream, decoding with charset.

      Otherwise identical to pipeFrom(Reader), including not closing source.

      Parameters:
      source - the bytes to read; must not be null
      charset - the encoding to decode with, e.g. StandardCharsets.UTF_8, or Charset.forName("Cp1047") for z/OS output
      Throws:
      IOException
    • captured

      String captured()
      The tail of everything written to this stream, for storing in an output property.

      Already masked, already bounded to the host's captured-output limit (the task's maximum comment size - older output is dropped from the front, silently and with no marker, matching what a Jython script task has always done), and with a single trailing newline removed so that a command whose output ends in a line break does not gain a blank last line.

      May be called at any point; it reflects everything written so far. Calling it does not consume or reset anything.

    • close

      void close()
      Flushes anything still buffered, including a final line with no trailing newline.

      Safe to call more than once, and safe to call on stdout() while stderr() is still being written - closing one never closes the shared sink or silences the other. Closing is optional: the host flushes and closes both streams when execute returns, on every path. Declared to not throw so a TaskOutput can sit in a try-with-resources without forcing a catch that has nothing useful to do.

      Specified by:
      close in interface AutoCloseable