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

  • Field Details

  • Constructor Details

    • CommandBuilder

      public CommandBuilder()

    • CommandBuilder

      public CommandBuilder(Collection<String> args)

    • CommandBuilder

      public CommandBuilder(String... args)

  • Method Details

    • 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&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 CommandBuilder that runs given command through cmd.exe /C
      Since:
      1.386

    • toWindowsCommand

      public CommandBuilder toWindowsCommand()
      Calls toWindowsCommand(false)
      See Also:

    • 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