Interface TaskExecutionContext
TaskExecutorExtension gets to see and change about the task it is running.
Reading the configuration
getConfiguration() returns the task's PluginTaskConfiguration itself, not a
wrapper. That means the platform's own reflection surface - getType().getDescriptor(),
PropertyDescriptor, PropertyKind - is how
you discover what a configuration contains, and pd.get(ci) is how you follow a
kind="ci" reference to the item it points at, at any depth.
An earlier version of this interface returned a narrow read-only wrapper instead, on the
reasoning that a task author should not have to see configuration-item types. It was withdrawn
because the wrapper could not be honest: reaching a referenced configuration's own properties needs
the reflection API, the same API is already visible to a bundle through the bridged
ConfigurationApi, and the wrapper's documented "references are only reachable as an id"
rule was therefore something an author could step around in two lines. One way of reading a
configuration, using the same API the host itself uses, is worth more than a boundary that was not
one.
Two consequences to know about. Property values you read are live: the
configuration handed to you is this execution's own copy, so writing to it will not corrupt the
stored release, but it will also not persist - the only way to record a result is
setOutputs(T) or setOutputProperty(java.lang.String, java.lang.Object). And a kind="ci" reference resolves
lazily when you first touch it, so resolve references inside execute, not from a thread that
outlives it.
For typed access, prefer bind(Class): task types are declared in
type-definitions.xml and have no Java class of their own, so a record you define is the
closest thing to a type for them.
Passwords
A password-typed property read as a plainString may be ciphertext - what you get depends on
how the item was loaded, which is not something you should have to reason about. Read it as a
Secret instead, via secret(String) or a Secret component on a bound record:
revealing it decrypts it and registers it for masking in one step.
Threading
Instances are supplied per execution. Most methods are not thread-safe and must be called from the thread that received the context; do not retain one beyond theTaskExecutorExtension.execute(com.xebialabs.xlrelease.osgi.api.tasks.TaskExecutionContext) call, since its buffered state is written back to the task
when execute returns.
The exceptions are deliberate, because output is usually produced concurrently with the work:
log(String), stdout(), stderr() and isAborted() are thread-safe
and may be used from a thread you started.
-
Method Summary
Modifier and TypeMethodDescriptionvoidaddComment(String markdown) Adds a markdown comment to the task - the channel a report, an agent transcript, or a chat answer is posted through.<T> TBinds the task's configuration to a record you define - the typed way to read a configuration.The comments already on the task, in chronological order, including ones a user added - not any commentaddComment(java.lang.String)buffered during this same execution (see its Javadoc).The task's configuration item - every declared input and output property, variable-resolved, with referenced configurations reachable through the platform's reflection API at any depth.getInputProperty(String name) Convenience for the common case of a text input.<T> Optional<T> getInputProperty(String name, Class<T> type) An input property declared on the task's configuration type, converted totype.<T> Optional<T> getOutputProperty(String name, Class<T> type) Reads back an output property - typically state this extension itself wrote before suspending.The id of the release the task belongs to.The id of the task being executed - useful for logging and for correlating with an external system.The name of the configuration type of this task, inprefix.Nameform.booleanWhether the release author has asked for this task to be aborted.booleanisResume()Whether this is a re-entry rather than the first execution of this task - that is, whether a previous call returnedTaskExecutionResult.suspendFor(java.time.Duration)orTaskExecutionResult.awaitSignal().voidAppends a line to the task's execution log.secret(ConfigurationItem ci, String name) A password-typed property of any configuration item you have reached, as aSecret.A password-typed property of the task's own configuration, as aSecret.voidsetOutputProperty(String name, Object value) Sets an output property declared on the task's configuration type.<T> voidsetOutputs(T record) Writes every component ofrecordinto the declared output property of the same name (orPropertyNameoverride) - the write-side counterpart ofbind(Class).voidsetStatusLine(String statusLine) Sets the task's status line - the short, single-line summary shown next to the task in the release flow, replacing any previous value.stderr()The task's error output.stdout()The task's standard output - the stream a release author reads in the UI when they open the task, streamed while the task runs.
-
Method Details
-
getTaskId
String getTaskId()The id of the task being executed - useful for logging and for correlating with an external system. -
getReleaseId
String getReleaseId()The id of the release the task belongs to. -
getTaskType
String getTaskType()The name of the configuration type of this task, inprefix.Nameform. Equal to the extension's ownTaskExecutorExtension.getTaskType(), and useful when one extension is registered for a family of types. -
isResume
boolean isResume()Whether this is a re-entry rather than the first execution of this task - that is, whether a previous call returnedTaskExecutionResult.suspendFor(java.time.Duration)orTaskExecutionResult.awaitSignal().This is the hook for writing a state machine in one method: branch on it, and read what the previous entry left in the output properties. Note that because job delivery is at-least-once, a
truehere does not guarantee the previous entry's work happened exactly once. -
getConfiguration
PluginTaskConfiguration getConfiguration()The task's configuration item - every declared input and output property, variable-resolved, with referenced configurations reachable through the platform's reflection API at any depth.See the class Javadoc for what "live" means here, and for why this is the item itself rather than a wrapper. Password properties may be ciphertext when read as a
String; usesecret(String)or aSecretrecord component.- See Also:
-
bind
Binds the task's configuration to a record you define - the typed way to read a configuration.Each record component is matched by name to a declared property (or by a
PropertyNameoverride) and converted to the component's type. A component may itself be a record, to follow akind="ci"reference, and that nests to any depth - including recursively, which is how a chain of references such as a jumpstation behind a jumpstation is read in one call. ASecretcomponent reads a password property without decrypting it until you ask.Because task types are synthetic - declared in
type-definitions.xml, with no Java class - a record is as close to a type as they get, and is worth defining even for a handful of properties.- Parameters:
recordType- a public record whose every component names a declared property- Throws:
ConfigurationBindingException- if a component names an undeclared property, its value cannot be converted to the component's type, or a reference chain exceeds the supported depth or cycles
-
getInputProperty
An input property declared on the task's configuration type, converted totype.A dynamic-access escape hatch for one-off lookups.
bind(Class)is the primary path for anything more, andsecret(String)is the right way to read a password.- Parameters:
name- the property name as declared intype-definitions.xmltype- the expected value type, e.g.String.class,Integer.class,Boolean.class- Returns:
- the value, or empty if unset
- Throws:
IllegalArgumentException- if no such property is declared on this type - a typo should fail loudly rather than read as an unset valueClassCastException- if the declared property cannot be viewed astype
-
getInputProperty
Convenience for the common case of a text input.- See Also:
-
secret
A password-typed property of the task's own configuration, as aSecret.- Parameters:
name- the property name as declared intype-definitions.xml- Returns:
- the secret, or empty if the property is unset
- Throws:
IllegalArgumentException- if no such property is declared, or it is not a password property - reading a non-secret as aSecretis a mistake worth failing on rather than silently allowing
-
secret
A password-typed property of any configuration item you have reached, as aSecret.The form to use for a referenced configuration - a connection, a server, a jumpstation - that you followed from
getConfiguration().- Parameters:
ci- the item the property belongs toname- the property name as declared onci's type- See Also:
-
setOutputs
<T> void setOutputs(T record) Writes every component ofrecordinto the declared output property of the same name (orPropertyNameoverride) - the write-side counterpart ofbind(Class). Equivalent to callingsetOutputProperty(java.lang.String, java.lang.Object)once per component, with the same conversion in reverse (e.g. an enum component becomes the constant's name).- Parameters:
record- a public record whose every component names a declared output property- Throws:
ConfigurationBindingException- if a component names an undeclared output property, or its value cannot be converted to that property's kind
-
setOutputProperty
Sets an output property declared on the task's configuration type. Values are persisted whenexecutereturns, and are visible to later tasks in the release through variable interpolation - and to the next entry of this same extension after a suspend, which is how state is carried across a wait.- Parameters:
name- the property name as declared intype-definitions.xmlvalue- the value;nullmeans no update: the property keeps its previously persisted value, as withsetOutputsgiven an emptyOptional. Within the same execution a bufferednullstill reads back as empty- Throws:
IllegalArgumentException- if no such property is declared on this type
-
getOutputProperty
Reads back an output property - typically state this extension itself wrote before suspending.- Throws:
IllegalArgumentException- if no such property is declared on this type- See Also:
-
stdout
TaskOutput stdout()The task's standard output - the stream a release author reads in the UI when they open the task, streamed while the task runs.Hand
TaskOutput.asOutputStream()to whatever produces output, or callTaskOutput.pipeFrom(java.io.Reader)when you hold the source yourself, and readTaskOutput.captured()afterwards for a bounded tail to store in an output property. The host masks, chunks, streams and bounds it; seeTaskOutput.Thread-safe. The same instance is returned on every call.
-
stderr
TaskOutput stderr()The task's error output. Separate fromstdout()for the purpose ofTaskOutput.captured(), sooutputanderrcan be stored separately; both interleave into the one task log in the order written.Thread-safe. The same instance is returned on every call.
-
log
Appends a line to the task's execution log. Convenience forstdout().asPrintStream().println(message), and the right thing to reach for when you just want to say something rather than pipe a stream.Distinct from server logging: use your own SLF4J logger for anything aimed at an operator reading server logs rather than at the release author.
Any value obtained through
Secret.reveal()during this execution is replaced by********on its way out. Secrets you got hold of some other way are not masked, because nothing told the host about them.Thread-safe.
-
isAborted
boolean isAborted()Whether the release author has asked for this task to be aborted.Poll it in any loop that runs for a while - waiting on an external system, iterating over work items - and return promptly when it turns
true; returningTaskExecutionResult.failed(String)with a short explanation is usually right. This is the cooperative half of abort; the other half isTaskExecutorExtension.onAbort(TaskExecutionContext), called concurrently so a blocking call this flag cannot reach can still be unblocked from the outside. Without either, a task that ignores both keeps running after the author thinks they stopped it.Once
trueit staystrue. Thread-safe. -
setStatusLine
Sets the task's status line - the short, single-line summary shown next to the task in the release flow, replacing any previous value. Use it for progress ("waiting for build #431"), not for detail; detail belongs instdout()orlog(String).Especially useful before suspending, so the release author can see why a task is still in progress.
-
addComment
Adds a markdown comment to the task - the channel a report, an agent transcript, or a chat answer is posted through. Comments are user-visible, rendered as markdown, and buffered like output properties: they are attached to the task whenexecutereturns, in the sameChangesthat also carries output properties and the status line - including when the task suspends or fails, so a chat answer or a failure explanation is never lost. Because of that buffering, a comment added during this call is not yet visible togetComments()within the same execution; read it back on the next entry after a suspend.Comments are not masked, unlike
log(String)and the output streams: do not put credentials in a comment.- Parameters:
markdown- the comment text, rendered as markdown; a blank value is silently ignored, the same convention the host's own comment buffering uses- Throws:
NullPointerException- ifmarkdownisnull
-
getComments
List<TaskComment> getComments()The comments already on the task, in chronological order, including ones a user added - not any commentaddComment(java.lang.String)buffered during this same execution (see its Javadoc). This is the read side of the channelAI: Chatuses for its input: a comment'sTaskComment.authorlets an extension recognise and skip its own prior comments instead of relying on marker text.
-