Interface TaskExecutionContext


public interface TaskExecutionContext
Everything a 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 plain String 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 the TaskExecutorExtension.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 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, in prefix.Name form. Equal to the extension's own TaskExecutorExtension.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 returned TaskExecutionResult.suspendFor(java.time.Duration) or TaskExecutionResult.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 true here 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; use secret(String) or a Secret record component.

      See Also:
    • bind

      <T> T bind(Class<T> recordType)
      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 PropertyName override) and converted to the component's type. A component may itself be a record, to follow a kind="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. A Secret component 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

      <T> Optional<T> getInputProperty(String name, Class<T> type)
      An input property declared on the task's configuration type, converted to type.

      A dynamic-access escape hatch for one-off lookups. bind(Class) is the primary path for anything more, and secret(String) is the right way to read a password.

      Parameters:
      name - the property name as declared in type-definitions.xml
      type - 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 value
      ClassCastException - if the declared property cannot be viewed as type
    • getInputProperty

      default Optional<String> getInputProperty(String name)
      Convenience for the common case of a text input.
      See Also:
    • secret

      Optional<Secret> secret(String name)
      A password-typed property of the task's own configuration, as a Secret.
      Parameters:
      name - the property name as declared in type-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 a Secret is a mistake worth failing on rather than silently allowing
    • secret

      A password-typed property of any configuration item you have reached, as a Secret.

      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 to
      name - the property name as declared on ci's type
      See Also:
    • setOutputs

      <T> void setOutputs(T record)
      Writes every component of record into the declared output property of the same name (or PropertyName override) - the write-side counterpart of bind(Class). Equivalent to calling setOutputProperty(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

      void setOutputProperty(String name, Object value)
      Sets an output property declared on the task's configuration type. Values are persisted when execute returns, 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 in type-definitions.xml
      value - the value; null means no update: the property keeps its previously persisted value, as with setOutputs given an empty Optional. Within the same execution a buffered null still reads back as empty
      Throws:
      IllegalArgumentException - if no such property is declared on this type
    • getOutputProperty

      <T> Optional<T> getOutputProperty(String name, Class<T> type)
      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 call TaskOutput.pipeFrom(java.io.Reader) when you hold the source yourself, and read TaskOutput.captured() afterwards for a bounded tail to store in an output property. The host masks, chunks, streams and bounds it; see TaskOutput.

      Thread-safe. The same instance is returned on every call.

    • stderr

      TaskOutput stderr()
      The task's error output. Separate from stdout() for the purpose of TaskOutput.captured(), so output and err can 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

      void log(String message)
      Appends a line to the task's execution log. Convenience for stdout().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; returning TaskExecutionResult.failed(String) with a short explanation is usually right. This is the cooperative half of abort; the other half is TaskExecutorExtension.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 true it stays true. Thread-safe.

    • setStatusLine

      void setStatusLine(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. Use it for progress ("waiting for build #431"), not for detail; detail belongs in stdout() or log(String).

      Especially useful before suspending, so the release author can see why a task is still in progress.

    • addComment

      void addComment(String markdown)
      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 when execute returns, in the same Changes that 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 to getComments() 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 - if markdown is null
    • getComments

      List<TaskComment> getComments()
      The comments already on the task, in chronological order, including ones a user added - not any comment addComment(java.lang.String) buffered during this same execution (see its Javadoc). This is the read side of the channel AI: Chat uses for its input: a comment's TaskComment.author lets an extension recognise and skip its own prior comments instead of relying on marker text.