Interface TaskOutput
- All Superinterfaces:
AutoCloseable
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()orasPrintStream()to whatever is producing output (such as an external command runner or streaming client). - You hold the source - call
pipeFrom(Reader)orpipeFrom(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.
TaskOutput, and stdout() and stderr() interleave in the task log in the
order they were actually written.
Thread safety
Unlike the rest ofTaskExecutionContext, 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 TypeMethodDescriptionThis stream as anOutputStream, for handing to something that writes bytes.This stream as aPrintStream, forprintln-style writing.captured()The tail of everything written to this stream, for storing in an output property.voidclose()Flushes anything still buffered, including a final line with no trailing newline.voidpipeFrom(InputStream source, Charset charset) Readssourceto exhaustion into this stream, decoding withcharset.voidReadssourceto exhaustion into this stream, a line at a time.
-
Method Details
-
asOutputStream
OutputStream asOutputStream()This stream as anOutputStream, 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 aPrintStream, forprintln-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
Readssourceto 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 benull- Throws:
IOException- if readingsourcefails. A failure to write the task log does not throw - task output is best-effort and must not fail the task.
-
pipeFrom
Readssourceto exhaustion into this stream, decoding withcharset.Otherwise identical to
pipeFrom(Reader), including not closingsource.- Parameters:
source- the bytes to read; must not benullcharset- the encoding to decode with, e.g.StandardCharsets.UTF_8, orCharset.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()whilestderr()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 whenexecutereturns, on every path. Declared to not throw so aTaskOutputcan sit in a try-with-resources without forcing acatchthat has nothing useful to do.- Specified by:
closein interfaceAutoCloseable
-