Package org.jenkinsci.plugins.durabletask

Class Controller

java.lang.Object

org.jenkinsci.plugins.durabletask.Controller

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

FileMonitoringTask.FileMonitoringController

public abstract class Controller
extends Object
implements Serializable

Defines how to control the execution of a task after it has started. Expected to be XStream and Java serializable.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
Controller()

Method Summary

Modifier and Type	Method	Description
abstract void	cleanup(FilePath workspace)	Cleans up after a task is done.
Integer	exitStatus(FilePath workspace)	Deprecated. use exitStatus(FilePath, Launcher, TaskListener) instead
Integer	exitStatus(FilePath workspace, Launcher launcher)	Deprecated. use exitStatus(FilePath, Launcher, TaskListener) instead
Integer	exitStatus(FilePath workspace, Launcher launcher, TaskListener logger)	Checks whether the task has finished.
String	getDiagnostics(FilePath workspace, Launcher launcher)	Should be overridden to provide specific information about the status of an external process, for diagnostic purposes.
byte[]	getOutput(FilePath workspace, Launcher launcher)	Obtain the process output.
void	stop(FilePath workspace)	Deprecated. use stop(FilePath, Launcher) instead
void	stop(FilePath workspace, Launcher launcher)	Tries to stop any running task.
void	watch(FilePath workspace, Handler handler, TaskListener listener)	Begins watching the process asynchronously, so that the master may receive notification when output is available or the process has exited.
abstract boolean	writeLog(FilePath workspace, OutputStream sink)	Obtains any new task log output.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Controller

public Controller()

Method Detail

watch

public void watch(@NonNull
                  FilePath workspace,
                  @NonNull
                  Handler handler,
                  @NonNull
                  TaskListener listener)
           throws IOException,
                  InterruptedException,
                  UnsupportedOperationException

Begins watching the process asynchronously, so that the master may receive notification when output is available or the process has exited. This should be called as soon as the process is launched, and thereafter whenever reconnecting to the agent. You should not call writeLog(hudson.FilePath, java.io.OutputStream) or cleanup(hudson.FilePath) in this case; you do not need to call exitStatus(FilePath, Launcher) frequently, though it is advisable to still call it occasionally to verify that the process is still running.

Parameters:

workspace - the workspace in use

handler - a remotable callback

listener - a remotable destination for messages

Throws:

IOException - if initiating the watch fails, for example with a ChannelClosedException

UnsupportedOperationException - when this mode is not available, so you must fall back to polling writeLog(hudson.FilePath, java.io.OutputStream) and exitStatus(FilePath, Launcher)

InterruptedException

writeLog

public abstract boolean writeLog(FilePath workspace,
                                 OutputStream sink)
                          throws IOException,
                                 InterruptedException

Obtains any new task log output. Could use a serializable field to keep track of how much output has been previously written.

Parameters:

workspace - the workspace in use

sink - where to send new log output

Returns:

true if something was written and the controller should be resaved, false if everything is idle

Throws:

IOException

InterruptedException

See Also:

DurableTask.charset(java.nio.charset.Charset), DurableTask.defaultCharset()

exitStatus

@CheckForNull
public Integer exitStatus(FilePath workspace,
                          Launcher launcher,
                          TaskListener logger)
                   throws IOException,
                          InterruptedException

Checks whether the task has finished.

Parameters:

workspace - the workspace in use

launcher - a way to start processes (currently unused)

logger - a way to report special messages

Returns:

an exit code (zero is successful), or null if the task appears to still be running

Throws:

IOException

InterruptedException

exitStatus

@Deprecated
@CheckForNull
public Integer exitStatus(FilePath workspace,
                          Launcher launcher)
                   throws IOException,
                          InterruptedException

Deprecated.

use exitStatus(FilePath, Launcher, TaskListener) instead

Throws:

IOException

InterruptedException

exitStatus

@Deprecated
@CheckForNull
public Integer exitStatus(FilePath workspace)
                   throws IOException,
                          InterruptedException

Deprecated.

use exitStatus(FilePath, Launcher, TaskListener) instead

Throws:

IOException

InterruptedException

getOutput

@NonNull
public byte[] getOutput(@NonNull
                        FilePath workspace,
                        @NonNull
                        Launcher launcher)
                 throws IOException,
                        InterruptedException

Obtain the process output. Intended for use after exitStatus(FilePath, Launcher) has returned a non-null status. The result is undefined if DurableTask.captureOutput() was not called before launch; generally an IOException will result.

Parameters:

workspace - the workspace in use

launcher - a way to start processes (currently unused)

Returns:

the output of the process as raw bytes (may be empty but not null)

Throws:

IOException

InterruptedException

See Also:

DurableTask.charset(java.nio.charset.Charset), DurableTask.defaultCharset()

stop

public void stop(FilePath workspace,
                 Launcher launcher)
          throws IOException,
                 InterruptedException

Tries to stop any running task.

Parameters:

workspace - the workspace in use

launcher - a way to start processes

Throws:

IOException

InterruptedException

stop

public void stop(FilePath workspace)
          throws IOException,
                 InterruptedException

Deprecated.

use stop(FilePath, Launcher) instead

Throws:

IOException

InterruptedException

cleanup

public abstract void cleanup(FilePath workspace)
                      throws IOException,
                             InterruptedException

Cleans up after a task is done. Should delete any temporary files created by DurableTask.launch(hudson.EnvVars, hudson.FilePath, hudson.Launcher, hudson.model.TaskListener).

Parameters:

workspace - the workspace in use

Throws:

IOException

InterruptedException

getDiagnostics

public String getDiagnostics(FilePath workspace,
                             Launcher launcher)
                      throws IOException,
                             InterruptedException

Should be overridden to provide specific information about the status of an external process, for diagnostic purposes.

Returns:

Object.toString() by default

Throws:

IOException

InterruptedException