hudson
Class Launcher

java.lang.Object
  hudson.Launcher

Direct Known Subclasses:

Launcher.LocalLauncher, Launcher.RemoteLauncher, WindowsRemoteLauncher

public abstract class Launcher
extends Object

Starts a process.

This hides the difference between running programs locally vs remotely.

'env' parameter

To allow important environment variables to be copied over to the remote machine, the 'env' parameter shouldn't contain default inherited environment variables (which often contains machine-specific information, like PATH, TIMEZONE, etc.)

Launcher is responsible for inheriting environment variables.

Author:

Kohsuke Kawaguchi

See Also:

FilePath.createLauncher(TaskListener)

Nested Class Summary

static class	Launcher.IOTriplet
static class	Launcher.LocalLauncher Launcher that launches process locally.
class	Launcher.ProcStarter Builder pattern for configuring a process to launch.
static class	Launcher.RemoteLauncher Launches processes remotely by using the given channel.
static interface	Launcher.RemoteProcess Remoting interface of a remote process

Field Summary

protected hudson.remoting.VirtualChannel	channel
protected TaskListener	listener
static boolean	showFullPath Debug option to display full current path instead of just the last token.

Constructor Summary

protected	Launcher(Launcher launcher) Constructor for a decorator.
	Launcher(TaskListener listener, hudson.remoting.VirtualChannel channel)

Method Summary

Launcher	decorateByEnv(EnvVars _env) Returns a decorated Launcher that automatically adds the specified environment variables.
Launcher	decorateByPrefix(String... prefix) Returns a decorated Launcher that puts the given set of arguments as a prefix to any commands that it invokes.
Launcher	decorateFor(Node node) Returns a decorated Launcher for the given node.
hudson.remoting.VirtualChannel	getChannel() Gets the channel that can be used to run a program remotely.
Computer	getComputer() Deprecated. since 2008-11-16. See the javadoc for why this is inherently unreliable. If you are trying to figure out the current Computer from within a build, use Computer.currentComputer()
TaskListener	getListener() Gets the TaskListener that this launcher uses to report the commands that it's executing.
boolean	isUnix() Returns true if this Launcher is going to launch on Unix.
abstract void	kill(Map<String,String> modelEnvVars) Calls ProcessTree.killAll(Map) to kill processes.
Launcher.ProcStarter	launch() Launches a process by using a builder-pattern to configure the parameters.
abstract Proc	launch(Launcher.ProcStarter starter) Primarily invoked from Launcher.ProcStarter.start() to start a process with a specific launcher.
Proc	launch(String[] cmd, boolean[] mask, Map<String,String> env, InputStream in, OutputStream out) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, boolean[] mask, Map<String,String> env, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, boolean[] mask, String[] env, InputStream in, OutputStream out) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, boolean[] mask, String[] env, InputStream in, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, boolean[] mask, String[] env, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, Map<String,String> env, InputStream in, OutputStream out) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, Map<String,String> env, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, String[] env, InputStream in, OutputStream out) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, String[] env, InputStream in, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String[] cmd, String[] env, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String cmd, Map<String,String> env, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
Proc	launch(String cmd, String[] env, OutputStream out, FilePath workDir) Deprecated. as of 1.311 Use launch() and its associated builder pattern
abstract hudson.remoting.Channel	launchChannel(String[] cmd, OutputStream out, FilePath workDir, Map<String,String> envVars) Launches a specified process and connects its input/output to a Channel, then return it.
protected void	maskedPrintCommandLine(List<String> cmd, boolean[] mask, FilePath workDir) Prints out the command line to the listener with some portions masked to prevent sensitive information from being recorded on the listener.
protected void	maskedPrintCommandLine(String[] cmd, boolean[] mask, FilePath workDir)
protected void	printCommandLine(String[] cmd, FilePath workDir) Prints out the command line to the listener so that users know what we are doing.

Methods inherited from class java.lang.Object

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

Field Detail

listener

protected final TaskListener listener

channel

protected final hudson.remoting.VirtualChannel channel

showFullPath

public static boolean showFullPath

Debug option to display full current path instead of just the last token.

Constructor Detail

Launcher

public Launcher(TaskListener listener,
                hudson.remoting.VirtualChannel channel)

Launcher

protected Launcher(Launcher launcher)

Constructor for a decorator.

Method Detail

getChannel

public hudson.remoting.VirtualChannel getChannel()

Gets the channel that can be used to run a program remotely.

Returns:

null if the target node is not configured to support this. this is a transitional measure. Note that a launcher for the master is always non-null.

getListener

public TaskListener getListener()

Gets the TaskListener that this launcher uses to report the commands that it's executing.

getComputer

public Computer getComputer()

Deprecated. since 2008-11-16. See the javadoc for why this is inherently unreliable. If you are trying to figure out the current Computer from within a build, use Computer.currentComputer()

If this Launcher is encapsulating an execution on a specific Computer, return it.

Because of the way internal Hudson abstractions are set up (that is, Launcher only needs a VirtualChannel to do its job and isn't really required that the channel comes from an existing Computer), this method may not always the right Computer instance.

Returns:

null if this launcher is not created from a Computer object.

launch

public final Launcher.ProcStarter launch()

Launches a process by using a builder-pattern to configure the parameters.

launch

public final Proc launch(String cmd,
                         Map<String,String> env,
                         OutputStream out,
                         FilePath workDir)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Throws:

IOException

launch

public final Proc launch(String[] cmd,
                         Map<String,String> env,
                         OutputStream out,
                         FilePath workDir)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Throws:

IOException

launch

public final Proc launch(String[] cmd,
                         Map<String,String> env,
                         InputStream in,
                         OutputStream out)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Throws:

IOException

launch

public final Proc launch(String[] cmd,
                         boolean[] mask,
                         Map<String,String> env,
                         OutputStream out,
                         FilePath workDir)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)

Parameters:

cmd - The command and all it's arguments.

mask - Which of the command and arguments should be masked from the listener

env - Environment variable overrides.

out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.

workDir - null if the working directory could be anything.

Returns:

The process of the command.

Throws:

IOException - When there are IO problems.

launch

public final Proc launch(String[] cmd,
                         boolean[] mask,
                         Map<String,String> env,
                         InputStream in,
                         OutputStream out)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)

Parameters:

cmd - The command and all it's arguments.

mask - Which of the command and arguments should be masked from the listener

env - Environment variable overrides.

in - null if there's no input.

out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.

Returns:

The process of the command.

Throws:

IOException - When there are IO problems.

launch

public final Proc launch(String cmd,
                         String[] env,
                         OutputStream out,
                         FilePath workDir)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Throws:

IOException

launch

public final Proc launch(String[] cmd,
                         String[] env,
                         OutputStream out,
                         FilePath workDir)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Throws:

IOException

launch

public final Proc launch(String[] cmd,
                         String[] env,
                         InputStream in,
                         OutputStream out)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Throws:

IOException

launch

public final Proc launch(String[] cmd,
                         boolean[] mask,
                         String[] env,
                         OutputStream out,
                         FilePath workDir)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)

Parameters:

cmd - The command and all it's arguments.

mask - Which of the command and arguments should be masked from the listener

env - Environment variable overrides.

out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.

workDir - null if the working directory could be anything.

Returns:

The process of the command.

Throws:

IOException - When there are IO problems.

launch

public final Proc launch(String[] cmd,
                         boolean[] mask,
                         String[] env,
                         InputStream in,
                         OutputStream out)
                  throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)

Parameters:

cmd - The command and all it's arguments.

mask - Which of the command and arguments should be masked from the listener

env - Environment variable overrides.

in - null if there's no input.

out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.

Returns:

The process of the command.

Throws:

IOException - When there are IO problems.

launch

public Proc launch(String[] cmd,
                   String[] env,
                   InputStream in,
                   OutputStream out,
                   FilePath workDir)
            throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Parameters:

env - Environment variable overrides.

in - null if there's no input.

workDir - null if the working directory could be anything.

out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.

Throws:

IOException

launch

public Proc launch(String[] cmd,
                   boolean[] mask,
                   String[] env,
                   InputStream in,
                   OutputStream out,
                   FilePath workDir)
            throws IOException

Deprecated. as of 1.311 Use launch() and its associated builder pattern

Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)

Parameters:

cmd - The command and all it's arguments.

mask - Which of the command and arguments should be masked from the listener

env - Environment variable overrides.

in - null if there's no input.

out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.

workDir - null if the working directory could be anything.

Returns:

The process of the command.

Throws:

IOException - When there are IO problems.

launch

public abstract Proc launch(Launcher.ProcStarter starter)
                     throws IOException

Primarily invoked from Launcher.ProcStarter.start() to start a process with a specific launcher.

Throws:

IOException

launchChannel

public abstract hudson.remoting.Channel launchChannel(String[] cmd,
                                                      OutputStream out,
                                                      FilePath workDir,
                                                      Map<String,String> envVars)
                                               throws IOException,
                                                      InterruptedException

Launches a specified process and connects its input/output to a Channel, then return it.

When the returned channel is terminated, the process will be killed.

Parameters:

out - Where the stderr from the launched process will be sent.

workDir - The working directory of the new process, or null to inherit from the current process

envVars - Environment variable overrides. In addition to what the current process is inherited (if this is going to be launched from a slave agent, that becomes the "current" process), these variables will be also set.

Throws:

IOException

InterruptedException

isUnix

public boolean isUnix()

Returns true if this Launcher is going to launch on Unix.

kill

public abstract void kill(Map<String,String> modelEnvVars)
                   throws IOException,
                          InterruptedException

Calls ProcessTree.killAll(Map) to kill processes.

Throws:

IOException

InterruptedException

printCommandLine

protected final void printCommandLine(String[] cmd,
                                      FilePath workDir)

Prints out the command line to the listener so that users know what we are doing.

maskedPrintCommandLine

protected final void maskedPrintCommandLine(List<String> cmd,
                                            boolean[] mask,
                                            FilePath workDir)

Prints out the command line to the listener with some portions masked to prevent sensitive information from being recorded on the listener.

Parameters:

cmd - The commands

mask - An array of booleans which control whether a cmd element should be masked (true) or remain unmasked (false).

workDir - The work dir.

maskedPrintCommandLine

protected final void maskedPrintCommandLine(String[] cmd,
                                            boolean[] mask,
                                            FilePath workDir)

decorateFor

public final Launcher decorateFor(Node node)

Returns a decorated Launcher for the given node.

decorateByPrefix

public final Launcher decorateByPrefix(String... prefix)

Returns a decorated Launcher that puts the given set of arguments as a prefix to any commands that it invokes.

Since:

1.299

decorateByEnv

public final Launcher decorateByEnv(EnvVars _env)

Returns a decorated Launcher that automatically adds the specified environment variables. Those that are specified in Launcher.ProcStarter.envs(String...) will take precedence over what's specified here.

Since:

1.489