Package com.cedarsoftware.util

Class Executor

java.lang.Object
com.cedarsoftware.util.Executor
public class Executor extends Object
A utility class for executing system commands and capturing their output.

This class provides a convenient wrapper around Java's Runtime.exec(String) methods, capturing both standard output and standard error streams. It handles stream management and process cleanup automatically.

Features:

  • Executes system commands with various parameter combinations
  • Captures stdout and stderr output
  • Supports environment variables
  • Supports working directory specification
  • Non-blocking output handling

Security Configuration

Due to the inherent security risks of executing arbitrary system commands, Executor is disabled by default and must be explicitly enabled. This is a security-first approach that requires intentional opt-in for command execution capabilities.

Security control can be configured via system property:

  • executor.enabled=false — Enable/disable all command execution (default: false)

Security Features

  • Disabled by Default: Command execution is disabled unless explicitly enabled
  • Explicit Opt-in: Users must consciously enable this dangerous functionality
  • Complete Control: Single property controls all execution methods
  • Clear Error Messages: SecurityExceptions provide instructions on how to enable

Security Warning

⚠️ WARNING: This class executes arbitrary system commands with the privileges of the JVM process. Only enable with trusted input and in environments where command execution is necessary.

Usage Example


 // Enable command execution (required)
 System.setProperty("executor.enabled", "true");

 // Now command execution will work
 Executor exec = new Executor();
 int exitCode = exec.exec("ls -l");
 String output = exec.getOut();

Breaking Change Notice

⚠️ BREAKING CHANGE: As of this version, Executor is disabled by default. Existing code that uses Executor will need to add System.setProperty("executor.enabled", "true") before using any Executor methods.

Basic Usage:


 // First, enable command execution (required)
 System.setProperty("executor.enabled", "true");
 
 // Then use Executor normally
 Executor exec = new Executor();
 int exitCode = exec.exec("ls -l");
 String output = exec.getOut();      // Get stdout
 String errors = exec.getError();    // Get stderr
Author:
John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Thread Safety: Instances of this class are not thread safe. Create a new Executor per command execution or synchronize externally if sharing across threads.

  • Constructor Details

    • Executor

      public Executor()

  • Method Details

    • execute

      public ExecutionResult execute(String command)
      Execute the supplied command line using the platform shell.
      Parameters:
      command - command to execute
      Returns:
      result of the execution
      Throws:
      SecurityException - if command execution is disabled

    • execute

      public ExecutionResult execute(String[] cmdarray)
      Execute the specified command array.
      Parameters:
      cmdarray - command and arguments
      Returns:
      result of the execution
      Throws:
      SecurityException - if command execution is disabled

    • execute

      public ExecutionResult execute(String command, String[] envp)
      Execute a command with environment variables.
      Parameters:
      command - command line to run
      envp - environment variables, may be null
      Returns:
      result of the execution
      Throws:
      SecurityException - if command execution is disabled

    • execute

      public ExecutionResult execute(String[] cmdarray, String[] envp)
      Execute a command array with environment variables.
      Parameters:
      cmdarray - command and arguments
      envp - environment variables, may be null
      Returns:
      result of the execution
      Throws:
      SecurityException - if command execution is disabled

    • execute

      public ExecutionResult execute(String command, String[] envp, File dir)
      Execute a command with optional environment and working directory.
      Parameters:
      command - command line to run
      envp - environment variables or null
      dir - working directory, may be null
      Returns:
      result of the execution
      Throws:
      SecurityException - if command execution is disabled

    • execute

      public ExecutionResult execute(String[] cmdarray, String[] envp, File dir)
      Execute a command array with optional environment and working directory.
      Parameters:
      cmdarray - command and arguments
      envp - environment variables or null
      dir - working directory, may be null
      Returns:
      result of the execution
      Throws:
      SecurityException - if command execution is disabled

    • exec

      public int exec(String command)
      Executes a command using the system's runtime environment.
      Parameters:
      command - the command to execute
      Returns:
      the exit value of the process (0 typically indicates success), or -1 if an error occurred starting the process
      Throws:
      SecurityException - if command execution is disabled

    • exec

      public int exec(String[] cmdarray)
      Executes a command array using the system's runtime environment.

      This version allows commands with arguments to be specified as separate array elements, avoiding issues with argument quoting and escaping.

      Parameters:
      cmdarray - array containing the command and its arguments
      Returns:
      the exit value of the process (0 typically indicates success), or -1 if an error occurred starting the process
      Throws:
      SecurityException - if command execution is disabled

    • exec

      public int exec(String command, String[] envp)
      Executes a command with specified environment variables.
      Parameters:
      command - the command to execute
      envp - array of strings, each element of which has environment variable settings in format name=value, or null if the subprocess should inherit the environment of the current process
      Returns:
      the exit value of the process (0 typically indicates success), or -1 if an error occurred starting the process
      Throws:
      SecurityException - if command execution is disabled

    • exec

      public int exec(String[] cmdarray, String[] envp)
      Executes a command array with specified environment variables.
      Parameters:
      cmdarray - array containing the command and its arguments
      envp - array of strings, each element of which has environment variable settings in format name=value, or null if the subprocess should inherit the environment of the current process
      Returns:
      the exit value of the process (0 typically indicates success), or -1 if an error occurred starting the process
      Throws:
      SecurityException - if command execution is disabled

    • exec

      public int exec(String command, String[] envp, File dir)
      Executes a command with specified environment variables and working directory.
      Parameters:
      command - the command to execute
      envp - array of strings, each element of which has environment variable settings in format name=value, or null if the subprocess should inherit the environment of the current process
      dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process
      Returns:
      the exit value of the process (0 typically indicates success), or -1 if an error occurred starting the process
      Throws:
      SecurityException - if command execution is disabled

    • exec

      public int exec(String[] cmdarray, String[] envp, File dir)
      Executes a command array with specified environment variables and working directory.
      Parameters:
      cmdarray - array containing the command and its arguments
      envp - array of strings, each element of which has environment variable settings in format name=value, or null if the subprocess should inherit the environment of the current process
      dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process
      Returns:
      the exit value of the process (0 typically indicates success), or -1 if an error occurred starting the process
      Throws:
      SecurityException - if command execution is disabled

    • getError

      public String getError()
      Returns the content written to standard error by the last executed command.
      Returns:
      the stderr output as a string, or null if no command has been executed

    • getOut

      public String getOut()
      Returns the content written to standard output by the last executed command.
      Returns:
      the stdout output as a string, or null if no command has been executed