hudson.util
Class ArgumentListBuilder

java.lang.Object
  hudson.util.ArgumentListBuilder

All Implemented Interfaces:

Serializable, Cloneable

public class ArgumentListBuilder
extends Object
implements Serializable, Cloneable

Used to build up arguments for a process invocation.

Author:

Kohsuke Kawaguchi

See Also:

Serialized Form

Constructor Summary

ArgumentListBuilder()

ArgumentListBuilder(String... args)

Method Summary

ArgumentListBuilder	add(File f)
ArgumentListBuilder	add(Object a)
ArgumentListBuilder	add(Object a, boolean mask)
ArgumentListBuilder	add(String... args)
ArgumentListBuilder	add(String a)
ArgumentListBuilder	add(String a, boolean mask) Optionally hide this part of the command line from being printed to the log.
ArgumentListBuilder	addKeyValuePair(String prefix, String key, String value, boolean mask)
ArgumentListBuilder	addKeyValuePairs(String prefix, Map<String,String> props) Adds key value pairs as "-Dkey=value -Dkey=value ..." -D portion is configurable as the 'prefix' parameter.
ArgumentListBuilder	addKeyValuePairs(String prefix, Map<String,String> props, Set<String> propsToMask) Adds key value pairs as "-Dkey=value -Dkey=value ..." with masking.
ArgumentListBuilder	addKeyValuePairsFromPropertyString(String prefix, String properties, VariableResolver vr) Adds key value pairs as "-Dkey=value -Dkey=value ..." by parsing a given string using Properties.
ArgumentListBuilder	addKeyValuePairsFromPropertyString(String prefix, String properties, VariableResolver vr, Set<String> propsToMask) Adds key value pairs as "-Dkey=value -Dkey=value ..." by parsing a given string using Properties with masking.
void	addMasked(String string) Add a masked argument
ArgumentListBuilder	addQuoted(String a) Adds an argument by quoting it.
ArgumentListBuilder	addQuoted(String a, boolean mask)
ArgumentListBuilder	addTokenized(String s) Decomposes the given token into multiple arguments by splitting via whitespace.
void	clear() Re-initializes the arguments list.
ArgumentListBuilder	clone()
boolean	hasMaskedArguments() Returns true if there are any masked arguments.
ArgumentListBuilder	prepend(String... args)
String[]	toCommandArray()
List<String>	toList()
boolean[]	toMaskArray() Returns an array of booleans where the masked arguments are marked as true
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.
ArgumentListBuilder	toWindowsCommand() Calls toWindowsCommand(false)
ArgumentListBuilder	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

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

Constructor Detail

ArgumentListBuilder

public ArgumentListBuilder()

ArgumentListBuilder

public ArgumentListBuilder(String... args)

Method Detail

add

public ArgumentListBuilder add(Object a)

add

public ArgumentListBuilder add(Object a,
                               boolean mask)

Since:

1.378

add

public ArgumentListBuilder add(File f)

add

public ArgumentListBuilder add(String a)

add

public ArgumentListBuilder add(String a,
                               boolean mask)

Optionally hide this part of the command line from being printed to the log.

Parameters:

a - a command argument

mask - true to suppress in output, false to print normally

Returns:

this

Since:

1.378

See Also:

Launcher.ProcStarter.masks(boolean[]), Launcher.maskedPrintCommandLine(List, boolean[], FilePath)

prepend

public ArgumentListBuilder prepend(String... args)

addQuoted

public ArgumentListBuilder 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 ArgumentListBuilder addQuoted(String a,
                                     boolean mask)

Since:

1.378

add

public ArgumentListBuilder add(String... args)

addTokenized

public ArgumentListBuilder addTokenized(String s)

Decomposes the given token into multiple arguments by splitting via whitespace.

addKeyValuePair

public ArgumentListBuilder addKeyValuePair(String prefix,
                                           String key,
                                           String value,
                                           boolean mask)

Since:

1.378

addKeyValuePairs

public ArgumentListBuilder 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 ArgumentListBuilder 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

addKeyValuePairsFromPropertyString

public ArgumentListBuilder addKeyValuePairsFromPropertyString(String prefix,
                                                              String properties,
                                                              VariableResolver vr)
                                                       throws IOException

Adds key value pairs as "-Dkey=value -Dkey=value ..." by parsing a given string using Properties.

Parameters:

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

properties - The persisted form of Properties. For example, "abc=def\nghi=jkl". Can be null, in which case this method becomes no-op.

vr - VariableResolver to be performed on the values.

Throws:

IOException

Since:

1.262

addKeyValuePairsFromPropertyString

public ArgumentListBuilder addKeyValuePairsFromPropertyString(String prefix,
                                                              String properties,
                                                              VariableResolver vr,
                                                              Set<String> propsToMask)
                                                       throws IOException

Adds key value pairs as "-Dkey=value -Dkey=value ..." by parsing a given string using Properties with masking.

Parameters:

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

properties - The persisted form of Properties. For example, "abc=def\nghi=jkl". Can be null, in which case this method becomes no-op.

vr - VariableResolver to be performed on the values.

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.

Throws:

IOException

Since:

1.378

toCommandArray

public String[] toCommandArray()

clone

public ArgumentListBuilder 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 ArgumentListBuilder 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 ArgumentListBuilder that runs given command through cmd.exe /C

Since:

1.386

toWindowsCommand

public ArgumentListBuilder toWindowsCommand()

Calls toWindowsCommand(false)

See Also:

toWindowsCommand(boolean)

hasMaskedArguments

public boolean hasMaskedArguments()

Returns true if there are any masked arguments.

Returns:

true if there are any masked arguments; false otherwise

toMaskArray

public boolean[] toMaskArray()

Returns an array of booleans where the masked arguments are marked as true

Returns:

an array of booleans.

addMasked

public void addMasked(String string)

Add a masked argument

Parameters:

string - the argument

toString

public String toString()

Debug/error message friendly output.

Overrides:

toString in class Object