Package hudson

Class Launcher.ProcStarter

java.lang.Object

hudson.Launcher.ProcStarter

Enclosing class:

Launcher

public final class Launcher.ProcStarter
extends Object

Builder pattern for configuring a process to launch.

Since:

1.311

Field Summary

Fields

Modifier and Type	Field	Description
protected List<String>	commands
protected String[]	envs
protected EnvVarsFilterableBuilder	envVarsFilterableBuilder	Represent the build step, either from legacy build process or from pipeline one
protected boolean[]	masks
protected FilePath	pwd
protected boolean	reverseStderr	True to reverse the I/O direction.
protected boolean	reverseStdin	True to reverse the I/O direction.
protected boolean	reverseStdout	True to reverse the I/O direction.
protected OutputStream	stderr
protected InputStream	stdin
protected OutputStream	stdout

Constructor Summary

Constructors

Constructor	Description
ProcStarter()

Method Summary

Modifier and Type	Method	Description
EnvVarsFilterableBuilder	buildStep()
Launcher.ProcStarter	buildStep(EnvVarsFilterableBuilder envVarsFilterableBuilder)	Specify the build step that want to run the command to enable the environment filters
Launcher.ProcStarter	cmdAsSingleString(String s)	Passes a white-space separated single-string command (like "cat abc def") and parse them as a command argument.
List<String>	cmds()
Launcher.ProcStarter	cmds(ArgumentListBuilder args)
Launcher.ProcStarter	cmds(File program, String... args)
Launcher.ProcStarter	cmds(String... args)
Launcher.ProcStarter	cmds(List<String> args)
Launcher.ProcStarter	copy()	Copies a Launcher.ProcStarter.
String[]	envs()	Gets a list of environment variables to be set.
Launcher.ProcStarter	envs(String... overrides)
Launcher.ProcStarter	envs(Map<String,String> overrides)	Sets the environment variable overrides.
int	join()	Starts the process and waits for its completion.
boolean[]	masks()
Launcher.ProcStarter	masks(boolean... masks)	Hide parts of the command line from being printed to the log.
FilePath	pwd()
Launcher.ProcStarter	pwd(FilePath workDir)	Sets the current directory.
Launcher.ProcStarter	pwd(File workDir)
Launcher.ProcStarter	pwd(String workDir)
boolean	quiet()
Launcher.ProcStarter	quiet(boolean quiet)	Allows Launcher.maskedPrintCommandLine(List, boolean[], FilePath) to be suppressed from Launcher.LocalLauncher.launch(hudson.Launcher.ProcStarter).
Launcher.ProcStarter	readStderr()	In addition to the effect of readStdout(), indicate that the caller will pump stderr from the child process separately from stdout.
Launcher.ProcStarter	readStdout()	Indicates that the caller will pump stdout from the child process via Proc.getStdout() (whereas by default you call stdout(OutputStream) and let Jenkins pump stdout into your OutputStream of choosing.
Proc	start()	Starts the new process as configured.
OutputStream	stderr()	Gets current STDERR destination.
Launcher.ProcStarter	stderr(OutputStream err)	Controls where the stderr of the process goes.
InputStream	stdin()	Gets current STDIN destination.
Launcher.ProcStarter	stdin(InputStream in)	Controls where the stdin of the process comes from.
OutputStream	stdout()	Gets current STDOUT destination.
Launcher.ProcStarter	stdout(TaskListener out)	Sends the stdout to the given TaskListener.
Launcher.ProcStarter	stdout(OutputStream out)	Sets STDOUT destination.
Launcher.ProcStarter	writeStdin()	Indicates that the caller will directly write to the child process stdin() via Proc.getStdin().

Methods inherited from class java.lang.Object

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

Field Detail

commands

protected List<String> commands

masks

@CheckForNull
protected boolean[] masks

pwd

@CheckForNull
protected FilePath pwd

stdout

@CheckForNull
protected OutputStream stdout

stderr

@CheckForNull
protected OutputStream stderr

stdin

@CheckForNull
protected InputStream stdin

envs

@CheckForNull
protected String[] envs

envVarsFilterableBuilder

@CheckForNull
@Restricted(org.kohsuke.accmod.restrictions.Beta.class)
protected EnvVarsFilterableBuilder envVarsFilterableBuilder

Represent the build step, either from legacy build process or from pipeline one

reverseStdin

protected boolean reverseStdin

True to reverse the I/O direction. For example, if reverseStdout==true, then we expose InputStream from Proc and expect the client to read from it, whereas normally we take OutputStream via stdout(OutputStream) and feed stdout into that output.

Since:

1.399

reverseStdout

protected boolean reverseStdout

True to reverse the I/O direction. For example, if reverseStdout==true, then we expose InputStream from Proc and expect the client to read from it, whereas normally we take OutputStream via stdout(OutputStream) and feed stdout into that output.

Since:

1.399

reverseStderr

protected boolean reverseStderr

True to reverse the I/O direction. For example, if reverseStdout==true, then we expose InputStream from Proc and expect the client to read from it, whereas normally we take OutputStream via stdout(OutputStream) and feed stdout into that output.

Since:

1.399

Constructor Detail

ProcStarter

public ProcStarter()

Method Detail

cmdAsSingleString

public Launcher.ProcStarter cmdAsSingleString(String s)

Passes a white-space separated single-string command (like "cat abc def") and parse them as a command argument. This method also handles quotes.

cmds

public Launcher.ProcStarter cmds(String... args)

cmds

public Launcher.ProcStarter cmds(File program,
                                 String... args)

cmds

public Launcher.ProcStarter cmds(List<String> args)

cmds

public Launcher.ProcStarter cmds(ArgumentListBuilder args)

cmds

public List<String> cmds()

masks

public Launcher.ProcStarter masks(@CheckForNull
                                  boolean... masks)

Hide parts of the command line from being printed to the log.

Parameters:

masks - true for each position in cmds(String[]) which should be masked, false to print

Returns:

this

See Also:

ArgumentListBuilder.add(String, boolean), Launcher.maskedPrintCommandLine(List, boolean[], FilePath)

masks

@CheckForNull
public boolean[] masks()

quiet

public Launcher.ProcStarter quiet(boolean quiet)

Allows Launcher.maskedPrintCommandLine(List, boolean[], FilePath) to be suppressed from Launcher.LocalLauncher.launch(hudson.Launcher.ProcStarter). Useful when the actual command being printed is noisy and unreadable and the caller would rather print diagnostic information in a customized way.

Parameters:

quiet - to suppress printing the command line when starting the process; false to keep default behavior of printing

Returns:

this

Since:

1.576

quiet

public boolean quiet()

Since:

1.576

pwd

public Launcher.ProcStarter pwd(@CheckForNull
                                FilePath workDir)

Sets the current directory.

Parameters:

workDir - Work directory to be used. If null, the default/current directory will be used by the process starter

Returns:

this

pwd

public Launcher.ProcStarter pwd(@NonNull
                                File workDir)

pwd

public Launcher.ProcStarter pwd(@NonNull
                                String workDir)

pwd

@CheckForNull
public FilePath pwd()

stdout

public Launcher.ProcStarter stdout(@CheckForNull
                                   OutputStream out)

Sets STDOUT destination.

Parameters:

out - Output stream. Use null to send STDOUT to /dev/null.

Returns:

this

stdout

public Launcher.ProcStarter stdout(@NonNull
                                   TaskListener out)

Sends the stdout to the given TaskListener.

Parameters:

out - Task listener (must be safely remotable)

Returns:

this

stdout

@CheckForNull
public OutputStream stdout()

Gets current STDOUT destination.

Returns:

STDOUT output stream. null if STDOUT is suppressed or undefined.

stderr

public Launcher.ProcStarter stderr(@CheckForNull
                                   OutputStream err)

Controls where the stderr of the process goes. By default, it's bundled into stdout.

stderr

@CheckForNull
public OutputStream stderr()

Gets current STDERR destination.

Returns:

STDERR output stream. null if suppressed or undefined.

stdin

@NonNull
public Launcher.ProcStarter stdin(@CheckForNull
                                  InputStream in)

Controls where the stdin of the process comes from. By default, /dev/null.

Returns:

this

stdin

@CheckForNull
public InputStream stdin()

Gets current STDIN destination.

Returns:

STDIN output stream. null if suppressed or undefined.

envs

public Launcher.ProcStarter envs(@NonNull
                                 Map<String,String> overrides)

Sets the environment variable overrides.

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

Parameters:

overrides - Environment variables to be overridden

Returns:

this

envs

public Launcher.ProcStarter envs(@CheckForNull
                                 String... overrides)

Parameters:

overrides - List of "VAR=VALUE". See envs(Map) for the semantics.

Returns:

this

envs

@NonNull
public String[] envs()

Gets a list of environment variables to be set. Returns an empty array if envs field has not been initialized.

Returns:

If initialized, returns a copy of internal envs array. Otherwise - a new empty array.

readStdout

public Launcher.ProcStarter readStdout()

Indicates that the caller will pump stdout from the child process via Proc.getStdout() (whereas by default you call stdout(OutputStream) and let Jenkins pump stdout into your OutputStream of choosing.

When this method is called, Proc.getStdout() will read the combined output of stdout/stderr from the child process, unless readStderr() is called separately, which lets the caller read those two streams separately.

Returns:

this

Since:

1.399

readStderr

public Launcher.ProcStarter readStderr()

In addition to the effect of readStdout(), indicate that the caller will pump stderr from the child process separately from stdout. The stderr will be readable from Proc.getStderr() while Proc.getStdout() reads from stdout.

Returns:

this

Since:

1.399

writeStdin

public Launcher.ProcStarter writeStdin()

Indicates that the caller will directly write to the child process stdin() via Proc.getStdin(). (Whereas by default you call stdin(InputStream) and let Jenkins pump your InputStream of choosing to stdin.)

Returns:

this

Since:

1.399

buildStep

@Restricted(org.kohsuke.accmod.restrictions.Beta.class)
public Launcher.ProcStarter buildStep(EnvVarsFilterableBuilder envVarsFilterableBuilder)

Specify the build step that want to run the command to enable the environment filters

Returns:

this

Since:

2.246

buildStep

@Restricted(org.kohsuke.accmod.restrictions.Beta.class)
@CheckForNull
public EnvVarsFilterableBuilder buildStep()

Returns:

if set, returns the build step that wants to run the command

Since:

2.246

start

public Proc start()
           throws IOException

Starts the new process as configured.

Throws:

IOException

join

public int join()
         throws IOException,
                InterruptedException

Starts the process and waits for its completion.

Returns:

Return code of the invoked process

Throws:

IOException - Operation error (e.g. remote call failure)

InterruptedException - The process has been interrupted

copy

@NonNull
public Launcher.ProcStarter copy()

Copies a Launcher.ProcStarter.