Package 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:

  • Constructor Details

    • ArgumentListBuilder

      public ArgumentListBuilder()

    • ArgumentListBuilder

      public ArgumentListBuilder(String... args)

  • Method Details

    • 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:

    • 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)

    • add

      public ArgumentListBuilder add(@NonNull Iterable<String> args)
      Since:
      2.72

    • 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<String> 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 resolve variables in properties string.
      Throws:
      IOException
      Since:
      1.262

    • addKeyValuePairsFromPropertyString

      public ArgumentListBuilder addKeyValuePairsFromPropertyString(String prefix, String properties, VariableResolver<String> 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 resolve variables in properties string.
      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&mno<pqr>stu|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:

    • 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

    • addMasked

      public ArgumentListBuilder addMasked(Secret s)

    • toString

      public String toString()
      Debug/error message friendly output.
      Overrides:
      toString in class Object