Interface TaskExecutorExtension

All Superinterfaces:
HostExtensionPoint

public interface TaskExecutorExtension extends HostExtensionPoint
Implemented by a plugin bundle to provide the behaviour of a custom task type.

An implementation is an ordinary Spring bean in the bundle's plugin context (see the X-Plugin-Context manifest header). Nothing here is OSGi-specific: no BundleActivator, no BundleContext, no Declarative Services annotations. The host discovers implementations through PluginExtensionRegistry and never registers them into the root ApplicationContext.

A complete task type is two things:

  1. a declaration in the bundle's type-definitions.xml, of a type extending xlrelease.PluginTaskConfiguration, which defines the properties a release author fills in; and
  2. one bean implementing this interface, whose getTaskType() returns that declared type's name.

Execution model

execute runs on a host worker thread, not on the caller's thread, and it may block. It is invoked from the same bounded pool that runs every other task job in the product, so a blocking call holds one of those slots for its duration - exactly as a Jython script does today. That is why a plain synchronous signature is acceptable on top of an asynchronous host.

Block only for short, bounded waits. A single request/response is fine; seconds, not minutes. Anything open-ended - waiting for a deployment, an approval, a remote job - must return TaskExecutionResult.suspendFor(java.time.Duration) or TaskExecutionResult.awaitSignal() instead of sleeping. This is not a style preference: a parked thread is heap state. It does not survive a restart, redeploy, crash or failover, whereas a suspended task is persisted and does. Blocking for a long wait would silently lose in-flight work on restart, and would pass testing, because short waits work fine.

The host does not interrupt execute. Interrupting a thread doing I/O can close the channel it is on and poison a pooled client held across executions - too high a price for cancellation the host cannot be sure is safe. Abort reaches a running execution two ways instead: TaskExecutionContext.isAborted() turns true for execute to poll, and onAbort(TaskExecutionContext) is called, concurrently, from a different thread. See onAbort(TaskExecutionContext) for what it is for and what it must not do.

execute may be entered more than once for the same logical step. Job delivery is at-least-once, so implementations must tolerate re-entry - make external calls idempotent, or record progress in output properties and check it on entry (see TaskExecutionContext.isResume()).

Threads you start are yours. You may create threads, including virtual threads, inside execute; the host neither provides nor bounds them, and does not stop them at teardown. Anything you start must be joined or completed before execute returns. A thread that outlives the call is untracked by the host and keeps your bundle's classloader alive, which prevents your plugin from being cleanly uninstalled. Note also that on JDK 21, blocking inside a synchronized block on a virtual thread pins its carrier thread and costs throughput; prefer java.util.concurrent.locks around I/O.

A thread you start does not inherit the release's authenticated identity. execute itself runs already authenticated as the release's script user (the same identity, resolved the same way, that a Jython task's script runs as - see the release's "Run automated tasks as user" property), so a bridged host API call made directly inside execute is authorized correctly with no extra work. That identity lives in a plain, non- inheritable ThreadLocal, though, so a thread you spawn does not carry it: a bridged API call made from that thread runs with whatever ambient identity the new thread happens to have - typically none - and fails authentication rather than silently running as the wrong user. Make bridged API calls directly on the execute thread, or hand results back to it and make the call there.

Failure

Return TaskExecutionResult.failed(String) for an expected failure with a message a release author can act on. A thrown exception is also treated as a failure, but the author sees a stack trace rather than an explanation, so prefer the explicit result.

See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    Runs the task.
    The name of the configuration type this extension implements, in prefix.Name form - for example "acme.HelloTask" - exactly as declared in the bundle's type-definitions.xml and as rendered by com.xebialabs.deployit.plugin.api.reflect.Type#toString().
    void
    Called when the release author aborts this execution, so the extension can release whatever it is holding - close a connection, cancel a remote job - and let a blocked execute unwind.
  • Method Details

    • getTaskType

      String getTaskType()
      The name of the configuration type this extension implements, in prefix.Name form - for example "acme.HelloTask" - exactly as declared in the bundle's type-definitions.xml and as rendered by com.xebialabs.deployit.plugin.api.reflect.Type#toString().

      This is the host's dispatch key: it is matched against the configuration type of the task being executed. It must be unique across all installed plugins; a duplicate is caught when a task of that type is dispatched, not at plugin installation time.

      Note that this is the configuration type the author declared, not task.getType() - which is xlrelease.PluginTask for every plugin task, since one compiled task class backs them all.

      Returns:
      the declared configuration type name; never null or blank
    • execute

      Runs the task.

      Called on a host worker thread. See the class Javadoc for the blocking, interruption, idempotency and thread-ownership rules that apply here - they are contractual, not advisory.

      Parameters:
      context - access to the task's properties, identity and execution log; never null
      Returns:
      what the host should do next; never null
      Throws:
      Exception - treated as a task failure; prefer TaskExecutionResult.failed(String) for expected failures
    • onAbort

      void onAbort(TaskExecutionContext context)
      Called when the release author aborts this execution, so the extension can release whatever it is holding - close a connection, cancel a remote job - and let a blocked execute unwind. This is the host's answer to not interrupting execute (see the class Javadoc): closing the resource yourself unblocks even a read the host could not interrupt, without the risk an interrupt would carry.

      Called at most once per abort, including when execute is not currently running because the task is suspended (TaskExecutionResult.suspendFor(java.time.Duration)) or waiting for a signal (TaskExecutionResult.awaitSignal()). In that case the host rebuilds a context from the task's persisted state and calls onAbort with that rebuilt context.

      Runs on a host thread that is not the one running execute - when execute is in flight, the two run concurrently. Implement it accordingly:

      • Return promptly. A short, bounded remote-cancel call is fine (same contract as a Jython abort script), including a bounded poll to observe remote termination and drain trailing diagnostics/output, but never open-ended waits or retries.
      • context.log(...) / context.stdout() / context.stderr() output written here is captured and appended to this execution's Activity Logs stream, so use this hook for final remote diagnostics before returning.
      • Do not call bridged host APIs here. They run as the release's authenticated identity only on the execute thread (see the class Javadoc); this thread has none.
      • A thrown exception is logged and otherwise ignored - it neither fails the task nor stops the abort, which proceeds regardless of what execute eventually returns.

      An extension that owns remote work beyond one execute call (for example a job triggered before suspending) should implement this and cancel that work here; leaving this empty in that case is incorrect. An extension holding nothing past the call has nothing to release, and an empty body is the correct implementation.

      Parameters:
      context - either the live context of the running execute call or a context rebuilt from persisted task state when the task was suspended/awaiting-signal at abort