Interface TaskExecutorExtension
- All Superinterfaces:
HostExtensionPoint
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:
- a declaration in the bundle's
type-definitions.xml, of a type extendingxlrelease.PluginTaskConfiguration, which defines the properties a release author fills in; and - 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 TypeMethodDescriptionexecute(TaskExecutionContext context) Runs the task.The name of the configuration type this extension implements, inprefix.Nameform - for example"acme.HelloTask"- exactly as declared in the bundle'stype-definitions.xmland as rendered bycom.xebialabs.deployit.plugin.api.reflect.Type#toString().voidonAbort(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 blockedexecuteunwind.
-
Method Details
-
getTaskType
String getTaskType()The name of the configuration type this extension implements, inprefix.Nameform - for example"acme.HelloTask"- exactly as declared in the bundle'stype-definitions.xmland as rendered bycom.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 isxlrelease.PluginTaskfor every plugin task, since one compiled task class backs them all.- Returns:
- the declared configuration type name; never
nullor 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; nevernull- Returns:
- what the host should do next; never
null - Throws:
Exception- treated as a task failure; preferTaskExecutionResult.failed(String)for expected failures
-
onAbort
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 blockedexecuteunwind. This is the host's answer to not interruptingexecute(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
executeis 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 callsonAbortwith that rebuilt context.Runs on a host thread that is not the one running
execute- whenexecuteis 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
executethread (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
executeeventually returns.
An extension that owns remote work beyond one
executecall (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 runningexecutecall or a context rebuilt from persisted task state when the task was suspended/awaiting-signal at abort
-