Package hudson

Class Launcher

java.lang.Object
hudson.Launcher
Direct Known Subclasses:
Launcher.DecoratedLauncher, Launcher.DummyLauncher, Launcher.LocalLauncher, Launcher.RemoteLauncher
public abstract class Launcher extends Object
Starts a process.

This hides the difference between running programs locally vs remotely.

'env' parameter

To allow important environment variables to be copied over to the remote machine, the 'env' parameter shouldn't contain default inherited environment variables (which often contains machine-specific information, like PATH, TIMEZONE, etc.)

Launcher is responsible for inheriting environment variables.

Author:
Kohsuke Kawaguchi
See Also:

  • Field Details

    • listener

      @NonNull protected final TaskListener listener

    • channel

      @CheckForNull protected final hudson.remoting.VirtualChannel channel

    • envVarsFilterRuleWrapper

      @Restricted(org.kohsuke.accmod.restrictions.Beta.class) protected EnvVarsFilterRuleWrapper envVarsFilterRuleWrapper

    • showFullPath

      public static boolean showFullPath
      Debug option to display full current path instead of just the last token.

  • Constructor Details

    • Launcher

      protected Launcher(@NonNull TaskListener listener, @CheckForNull hudson.remoting.VirtualChannel channel)

    • Launcher

      protected Launcher(@NonNull Launcher launcher)
      Constructor for a decorator.
      Parameters:
      launcher - Launcher to be decorated

  • Method Details

    • prepareFilterRules

      @Restricted(org.kohsuke.accmod.restrictions.Beta.class) public void prepareFilterRules(@CheckForNull Run<?,?> run, @NonNull EnvVarsFilterableBuilder builder)
      Build the environment filter rules that will be applied on the environment variables
      Parameters:
      run - The run that requested the command interpretation, could be null if outside of a run context.
      builder - The builder that asked to run this command
      Since:
      2.246

    • setEnvVarsFilterRuleWrapper

      @Restricted(org.kohsuke.accmod.restrictions.Beta.class) protected void setEnvVarsFilterRuleWrapper(EnvVarsFilterRuleWrapper envVarsFilterRuleWrapper)

    • getChannel

      @CheckForNull public hudson.remoting.VirtualChannel getChannel()
      Gets the channel that can be used to run a program remotely.
      Returns:
      null if the target node is not configured to support this. this is a transitional measure. Note that a launcher for the built-in node is always non-null.

    • getListener

      @NonNull public TaskListener getListener()
      Gets the TaskListener that this launcher uses to report the commands that it's executing.
      Returns:
      Task listener

    • getComputer

      @Deprecated @CheckForNull public Computer getComputer()
      Deprecated.
      since 2008-11-16. See the javadoc for why this is inherently unreliable. If you are trying to figure out the current Computer from within a build, use FilePath.toComputer() or Computer.currentComputer().
      If this Launcher is encapsulating an execution on a specific Computer, return it.

      Because of the way internal Hudson abstractions are set up (that is, Launcher only needs a VirtualChannel to do its job and isn't really required that the channel comes from an existing Computer), this method may not always the right Computer instance.

      Returns:
      null if this launcher is not created from a Computer object.

    • launch

      @NonNull public final Launcher.ProcStarter launch()
      Launches a process by using a builder-pattern to configure the parameters.

    • launch

      @Deprecated public final Proc launch(String cmd, Map<String,String> env, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Throws:
      IOException

    • launch

      @Deprecated public final Proc launch(String[] cmd, Map<String,String> env, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Throws:
      IOException

    • launch

      @Deprecated public final Proc launch(String[] cmd, Map<String,String> env, InputStream in, OutputStream out) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Throws:
      IOException

    • launch

      @Deprecated public final Proc launch(String[] cmd, boolean[] mask, Map<String,String> env, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)
      Parameters:
      cmd - The command and all it's arguments.
      mask - Which of the command and arguments should be masked from the listener
      env - Environment variable overrides.
      out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.
      workDir - null if the working directory could be anything.
      Returns:
      The process of the command.
      Throws:
      IOException - When there are IO problems.

    • launch

      @Deprecated public final Proc launch(String[] cmd, boolean[] mask, Map<String,String> env, InputStream in, OutputStream out) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)
      Parameters:
      cmd - The command and all it's arguments.
      mask - Which of the command and arguments should be masked from the listener
      env - Environment variable overrides.
      in - null if there's no input.
      out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.
      Returns:
      The process of the command.
      Throws:
      IOException - When there are IO problems.

    • launch

      @Deprecated public final Proc launch(String cmd, String[] env, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Throws:
      IOException

    • launch

      @Deprecated public final Proc launch(String[] cmd, String[] env, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Throws:
      IOException

    • launch

      @Deprecated public final Proc launch(String[] cmd, String[] env, InputStream in, OutputStream out) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Throws:
      IOException

    • launch

      @Deprecated public final Proc launch(String[] cmd, boolean[] mask, String[] env, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)
      Parameters:
      cmd - The command and all it's arguments.
      mask - Which of the command and arguments should be masked from the listener
      env - Environment variable overrides.
      out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.
      workDir - null if the working directory could be anything.
      Returns:
      The process of the command.
      Throws:
      IOException - When there are IO problems.

    • launch

      @Deprecated public final Proc launch(String[] cmd, boolean[] mask, String[] env, InputStream in, OutputStream out) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)
      Parameters:
      cmd - The command and all it's arguments.
      mask - Which of the command and arguments should be masked from the listener
      env - Environment variable overrides.
      in - null if there's no input.
      out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.
      Returns:
      The process of the command.
      Throws:
      IOException - When there are IO problems.

    • launch

      @Deprecated public Proc launch(String[] cmd, String[] env, InputStream in, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Parameters:
      env - Environment variable overrides.
      in - null if there's no input.
      out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.
      workDir - null if the working directory could be anything.
      Throws:
      IOException

    • launch

      @Deprecated public Proc launch(String[] cmd, boolean[] mask, String[] env, InputStream in, OutputStream out, FilePath workDir) throws IOException
      Deprecated.
      as of 1.311 Use launch() and its associated builder pattern
      Launch a command with optional censoring of arguments from the listener (Note: The censored portions will remain visible through /proc, pargs, process explorer, etc. i.e. people logged in on the same machine This version of the launch command just ensures that it is not visible from a build log which is exposed via the web)
      Parameters:
      cmd - The command and all it's arguments.
      mask - Which of the command and arguments should be masked from the listener
      env - Environment variable overrides.
      in - null if there's no input.
      out - stdout and stderr of the process will be sent to this stream. the stream won't be closed.
      workDir - null if the working directory could be anything.
      Returns:
      The process of the command.
      Throws:
      IOException - When there are IO problems.

    • launch

      public abstract Proc launch(@NonNull Launcher.ProcStarter starter) throws IOException
      Primarily invoked from Launcher.ProcStarter.start() to start a process with a specific launcher.
      Throws:
      IOException

    • launchChannel

      public abstract hudson.remoting.Channel launchChannel(@NonNull String[] cmd, @NonNull OutputStream out, @CheckForNull FilePath workDir, @NonNull Map<String,String> envVars) throws IOException, InterruptedException
      Launches a specified process and connects its input/output to a Channel, then return it.

      When the returned channel is terminated, the process will be killed.

      Parameters:
      cmd - The commands.
      out - Where the stderr from the launched process will be sent.
      workDir - The working directory of the new process, or null to inherit from the current process
      envVars - Environment variable overrides. In addition to what the current process is inherited (if this is going to be launched from an agent, that becomes the "current" process), these variables will be also set.
      Throws:
      IOException
      InterruptedException

    • isUnix

      public boolean isUnix()
      Returns true if this Launcher is going to launch on Unix.

    • kill

      public abstract void kill(Map<String,String> modelEnvVars) throws IOException, InterruptedException
      Calls ProcessTree.killAll(Map) to kill processes.
      Throws:
      IOException
      InterruptedException

    • printCommandLine

      protected final void printCommandLine(@NonNull String[] cmd, @CheckForNull FilePath workDir)
      Prints out the command line to the listener so that users know what we are doing.

    • maskedPrintCommandLine

      protected final void maskedPrintCommandLine(@NonNull List<String> cmd, @CheckForNull boolean[] mask, @CheckForNull FilePath workDir)
      Prints out the command line to the listener with some portions masked to prevent sensitive information from being recorded on the listener.
      Parameters:
      cmd - The commands
      mask - An array of booleans which control whether a cmd element should be masked (true) or remain unmasked (false).
      workDir - The work dir.

    • maskedPrintCommandLine

      protected final void maskedPrintCommandLine(@NonNull String[] cmd, @NonNull boolean[] mask, @CheckForNull FilePath workDir)

    • decorateFor

      @NonNull public final Launcher decorateFor(@NonNull Node node)
      Returns a decorated Launcher for the given node.
      Parameters:
      node - Node for which this launcher is created.
      Returns:
      Decorated instance of the Launcher.

    • decorateByPrefix

      @NonNull public final Launcher decorateByPrefix(String... prefix)
      Returns a decorated Launcher that puts the given set of arguments as a prefix to any commands that it invokes.
      Parameters:
      prefix - Prefixes to be appended
      Since:
      1.299

    • decorateByEnv

      @NonNull public final Launcher decorateByEnv(@NonNull EnvVars _env)
      Returns a decorated Launcher that automatically adds the specified environment variables. Those that are specified in Launcher.ProcStarter.envs(String...) will take precedence over what's specified here.
      Since:
      1.489