org.jenkinsci.utils.process

Class CommandBuilder

java.lang.Object

org.jenkinsci.utils.process.CommandBuilder

All Implemented Interfaces:

Serializable, Cloneable

public class CommandBuilder
extends Object
implements Serializable, Cloneable

Used to build up arguments for a process invocation.

Most of the methods are for adding arguments. To simplify this, we have all kinds of overloaded add(String) methods. These methods are null safe, in that if null is passed as an argument they get ignored.

Configuring other parts of the process invocation isn't complete, except pwd(File). When you find a need to add more, please add them.

Once enough details are configured, use system() or popen() to run them. Alternatively, use build() to get a configured ProcessBuilder and then handle the output yourself.

Author:

Kohsuke Kawaguchi

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
Map<String,String>	env

Constructor Summary

Constructors

Constructor and Description
CommandBuilder()
CommandBuilder(Collection<String> args)
CommandBuilder(String... args)

Method Summary

Methods

Modifier and Type	Method and Description
CommandBuilder	add(CommandBuilder cmds)
CommandBuilder	add(File f)
CommandBuilder	add(Object... args)
CommandBuilder	add(Object a)
CommandBuilder	add(Object a, boolean mask)
CommandBuilder	add(String... args)
CommandBuilder	add(String a)
CommandBuilder	addAll(Collection<String> args)
CommandBuilder	addKeyValuePair(String prefix, String key, String value)
CommandBuilder	addKeyValuePairs(String prefix, Map<String,String> props) Adds key value pairs as "-Dkey=value -Dkey=value ..." -D portion is configurable as the 'prefix' parameter.
CommandBuilder	addKeyValuePairs(String prefix, Map<String,String> props, Set<String> propsToMask) Adds key value pairs as "-Dkey=value -Dkey=value ..." with masking.
CommandBuilder	addQuoted(String a) Adds an argument by quoting it.
CommandBuilder	addQuoted(String a, boolean mask)
ProcessBuilder	build()
void	clear() Re-initializes the arguments list.
CommandBuilder	clone()
boolean	equals(Object o)
int	hashCode()
ProcessInputStream	popen() Executes a process and read its output.
CommandBuilder	prepend(String... args)
CommandBuilder	pwd(File dir)
int	system() Executes a process and waits for that to complete.
String[]	toCommandArray()
List<String>	toList()
String	toString() Debug/error message friendly output.
String	toStringWithQuote() Just adds quotes around args containing spaces, but no other special characters, so this method should generally be used only for informational/logging purposes.
CommandBuilder	toWindowsCommand() Calls toWindowsCommand(false)
CommandBuilder	toWindowsCommand(boolean escapeVars) Wrap command in a CMD.EXE call so we can return the exit code (ERRORLEVEL).

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

env

public final Map<String,String> env

Constructor Detail

CommandBuilder

public CommandBuilder()

CommandBuilder

public CommandBuilder(Collection<String> args)

CommandBuilder

public CommandBuilder(String... args)

Method Detail

build

public ProcessBuilder build()

system

public int system()
           throws IOException,
                  InterruptedException

Executes a process and waits for that to complete. stdin/out/err will be the same with that of the calling process. See http://linux.die.net/man/3/system

Throws:

IOException

InterruptedException

popen

public ProcessInputStream popen()
                         throws IOException

Executes a process and read its output. See http://linux.die.net/man/3/popen

Throws:

IOException

pwd

public CommandBuilder pwd(File dir)

add

public CommandBuilder add(Object a)

add

public CommandBuilder add(Object a,
                 boolean mask)

Since:

1.378

add

public CommandBuilder add(File f)

add

public CommandBuilder add(String a)

prepend

public CommandBuilder prepend(String... args)

addQuoted

public CommandBuilder addQuoted(String a)

Adds an argument by quoting it. This is necessary only in a rare circumstance, such as when adding argument for ssh and rsh. Normal process invocations don't need it, because each argument is treated as its own string and never merged into one.

addQuoted

public CommandBuilder addQuoted(String a,
                       boolean mask)

Since:

1.378

add

public CommandBuilder add(Object... args)

add

public CommandBuilder add(String... args)

add

public CommandBuilder add(CommandBuilder cmds)

addAll

public CommandBuilder addAll(Collection<String> args)

addKeyValuePair

public CommandBuilder addKeyValuePair(String prefix,
                             String key,
                             String value)

Since:

1.378

addKeyValuePairs

public CommandBuilder addKeyValuePairs(String prefix,
                              Map<String,String> props)

Adds key value pairs as "-Dkey=value -Dkey=value ..." -D portion is configurable as the 'prefix' parameter.

Since:

1.114

addKeyValuePairs

public CommandBuilder addKeyValuePairs(String prefix,
                              Map<String,String> props,
                              Set<String> propsToMask)

Adds key value pairs as "-Dkey=value -Dkey=value ..." with masking.

Parameters:

prefix - Configures the -D portion of the example. Defaults to -D if null.

props - The map of key/value pairs to add

propsToMask - Set containing key names to mark as masked in the argument list. Key names that do not exist in the set will be added unmasked.

Since:

1.378

toCommandArray

public String[] toCommandArray()

clone

public CommandBuilder clone()

Overrides:

clone in class Object

clear

public void clear()

Re-initializes the arguments list.

toList

public List<String> toList()

toStringWithQuote

public String toStringWithQuote()

Just adds quotes around args containing spaces, but no other special characters, so this method should generally be used only for informational/logging purposes.

toWindowsCommand

public CommandBuilder toWindowsCommand(boolean escapeVars)

Wrap command in a CMD.EXE call so we can return the exit code (ERRORLEVEL). This method takes care of escaping special characters in the command, which is needed since the command is now passed as a string to the CMD.EXE shell. This is done as follows: Wrap arguments in double quotes if they contain any of: space *?,;^&<>|" and if escapeVars is true, % followed by a letter.
When testing from command prompt, these characters also need to be prepended with a ^ character: ^&<>| -- however, invoking cmd.exe from Jenkins does not seem to require this extra escaping so it is not added by this method.
A " is prepended with another " character. Note: Windows has issues escaping some combinations of quotes and spaces. Quotes should be avoided.
If escapeVars is true, a % followed by a letter has that letter wrapped in double quotes, to avoid possible variable expansion. ie, %foo% becomes "%"f"oo%". The second % does not need special handling because it is not followed by a letter.
Example: "-Dfoo=*abc?def;ghi^jkl&mnostu|vwx""yz%"e"nd"

Parameters:

escapeVars - True to escape %VAR% references; false to leave these alone so they may be expanded when the command is run

Returns:

new CommandBuilder that runs given command through cmd.exe /C

Since:

1.386

toWindowsCommand

public CommandBuilder toWindowsCommand()

Calls toWindowsCommand(false)

See Also:

toWindowsCommand(boolean)

toString

public String toString()

Debug/error message friendly output.

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object