Package rife.bld.extension

Class ExecOperation

java.lang.Object
rife.bld.operations.AbstractOperation<ExecOperation>
rife.bld.extension.ExecOperation
public class ExecOperation extends AbstractOperation<ExecOperation>
Executes a command on the command line.
Since:
1.0
Author:
Erik C. Thauvin

  • Constructor Details

    • ExecOperation

      public ExecOperation()

  • Method Details

    • execute

      public void execute() throws Exception
      Specified by:
      execute in class AbstractOperation<ExecOperation>
      Throws:
      Exception

    • isAix

      public static boolean isAix()
      Determines if the current operating system is AIX.
      Returns:
      true if the operating system is identified as AIX, false otherwise
      See Also:

    • isCygwin

      public static boolean isCygwin()
      Determines if the current operating system is Cygwin.
      Returns:
      true if the operating system is identified as Cygwin, false otherwise
      See Also:

    • isFreeBsd

      public static boolean isFreeBsd()
      Determines if the current operating system is FreeBSD.
      Returns:
      true if the operating system is FreeBSD, false otherwise
      See Also:

    • isLinux

      public static boolean isLinux()
      Determines if the operating system is Linux.
      Returns:
      true if the operating system is Linux, false otherwise
      See Also:

    • isMacOS

      public static boolean isMacOS()
      Determines if the current operating system is macOS.
      Returns:
      true if the OS is macOS, false otherwise
      See Also:

    • isMingw

      public static boolean isMingw()
      Determines if the current operating system is MinGW.
      Returns:
      true if the operating system is identified as MinGW, false otherwise
      See Also:

    • isOpenVms

      public static boolean isOpenVms()
      Determines if the current operating system is OpenVMS.
      Returns:
      true if the operating system is OpenVMS, false otherwise
      See Also:

    • isSolaris

      public static boolean isSolaris()
      Determines if the current operating system is Solaris.
      Returns:
      true if the operating system is Solaris, false otherwise
      See Also:

    • isWindows

      public static boolean isWindows()
      Determines if the current operating system is Windows.
      Returns:
      true if the operating system is Windows, false otherwise
      See Also:

    • command

      public ExecOperation command(@NonNull String... args)
      Configures the command and arguments to be executed.

      For example:

      • command("cmd", "/c", "stop.bat")
      • command("./stop.sh"
      Parameters:
      args - one or more arguments, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • command

      public List<String> command()
      Returns the command and arguments to be executed.

      The returned list is mutable and can be modified directly before calling execute(). This allows callers to append flags or manipulate arguments conditionally: 

      
 var op = new ExecOperation().command("git", "status");
 if (verbose) {
     op.command().add("--verbose");
 }
 op.execute();
      Returns:
      the mutable command and arguments list, never null

    • command

      public final ExecOperation command(@NonNull Collection<String> args)
      Configures the command and arguments to be executed.
      Parameters:
      args - the list of arguments, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • env

      public ExecOperation env(@NonNull String name, @NonNull String value)
      Adds an environment variable for the command.

      These variables are merged with the current process environment. Existing variables with the same name are overridden.

      Parameters:
      name - the variable name, must not be null
      value - the variable value, must not be null
      Returns:
      this operation instance
      Throws:
      NullPointerException - if name or value is null
      See Also:

    • env

      public ExecOperation env(@NonNull Map<String,String> vars)
      Adds environment variables for the command.

      These variables are merged with the current process environment. Existing variables with the same name are overridden.

      Parameters:
      vars - the map of environment variables, must not be null
      Returns:
      this operation instance
      Throws:
      NullPointerException - if vars is null
      See Also:

    • env

      public Map<String,String> env()
      Returns the environment variables to be set for the command.

      The returned map is mutable and can be modified directly before calling execute().

      Returns:
      the mutable environment variables map, never null

    • failOnExit

      public ExecOperation failOnExit(boolean failOnExit)
      Configures whether the operation should fail if the command exit value/status is not 0.

      Default is TRUE

      Parameters:
      failOnExit - The fail on exit toggle
      Returns:
      this operation instance.

    • fromProject

      public ExecOperation fromProject(@NonNull BaseProject project)
      Configures an Exec operation from a BaseProject.

      The work directory is automatically set to the project's working directory.

      Parameters:
      project - the project, must not be null
      Returns:
      this operation instance
      Throws:
      NullPointerException - if project is null

    • inheritIO

      public ExecOperation inheritIO(boolean inheritIO)
      Configures whether the child process should inherit the I/O streams of the current JVM.

      When true, the child process uses the same stdin, stdout, and stderr as the current Java process. This enables interactive commands, preserves ANSI colors, and allows progress bars to display correctly. Output is not captured by the logger and cannot be asserted in tests.

      When false, stdout and stderr are merged and captured through the logger. This makes output testable and keeps it in the build log, but breaks interactive prompts and ANSI formatting.

      Default is TRUE

      Parameters:
      inheritIO - true to inherit I/O, false to capture output
      Returns:
      this operation instance

    • isFailOnExit

      public boolean isFailOnExit()
      Returns whether the operation should fail if the command exit value/status is not 0.
      Returns:
      true or false

    • isInheritIO

      public boolean isInheritIO()
      Returns whether the child process inherits the I/O streams of the current JVM.
      Returns:
      true if I/O is inherited (default), false if output is captured
      See Also:

    • onLinux

      public ExecOperation onLinux(@NonNull String... args)
      If the current OS is Linux, configures the command and arguments to be executed. If not Linux, this call is ignored.
      Parameters:
      args - the command to use on Linux, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • onLinux

      public ExecOperation onLinux(@NonNull Collection<String> args)
      If the current OS is Linux, configures the command and arguments to be executed. If not Linux, this call is ignored.
      Parameters:
      args - the command to use on Linux, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • onMacOS

      public ExecOperation onMacOS(@NonNull String... args)
      If the current OS is macOS, configures the command and arguments to be executed. If not macOS, this call is ignored.
      Parameters:
      args - the command to use on macOS, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • onMacOS

      public ExecOperation onMacOS(@NonNull Collection<String> args)
      If the current OS is macOS, configures the command and arguments to be executed. If not macOS, this call is ignored.
      Parameters:
      args - the command to use on macOS, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • onUnix

      public ExecOperation onUnix(@NonNull String... args)
      If the current OS is Unix-like (Linux, macOS, FreeBSD, Solaris, AIX), configures the command and arguments to be executed. If Windows, this call is ignored.

      This is a convenience method for commands that work on all Unix-like systems.

      Parameters:
      args - the command to use on Unix-like systems, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • onUnix

      public ExecOperation onUnix(@NonNull Collection<String> args)
      If the current OS is Unix-like, configures the command and arguments to be executed. If Windows, this call is ignored.
      Parameters:
      args - the command to use on Unix-like systems, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • onWindows

      public ExecOperation onWindows(@NonNull String... args)
      If the current OS is Windows, configures the command and arguments to be executed. If not Windows, this call is ignored.

      Allows platform-specific commands to be declared fluently: 

      
 new ExecOperation()
     .fromProject(this)
     .onWindows("cmd", "/c", "build.bat")
     .onUnix("./build.sh")
     .execute();

      Note: If multiple matching calls are made, the last one wins.

      Parameters:
      args - the command to use on Windows, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • onWindows

      public ExecOperation onWindows(@NonNull Collection<String> args)
      If the current OS is Windows, configures the command and arguments to be executed. If not Windows, this call is ignored.
      Parameters:
      args - the command to use on Windows, must not be null or contain null/empty elements
      Returns:
      this operation instance
      Throws:
      NullPointerException - if args is null
      IllegalArgumentException - if args contains null or empty elements
      See Also:

    • outputConsumer

      public ExecOperation outputConsumer(@NonNull Consumer<String> outputConsumer)
      Sets a consumer to receive output lines when not inheriting I/O.

      Only called when isInheritIO() is false. Default logs at INFO level.

      Parameters:
      outputConsumer - the output consumer, must not be null
      Returns:
      this operation instance
      Throws:
      NullPointerException - if outputConsumer is null

    • timeout

      public ExecOperation timeout(long timeout)
      Configure the command timeout.
      Parameters:
      timeout - The timeout in seconds, use a negative number for no timeout
      Returns:
      this operation instance
      Throws:
      IllegalArgumentException - if timeout is 0

    • timeout

      public long timeout()
      Returns the command timeout.
      Returns:
      the timeout in seconds

    • workDir

      public ExecOperation workDir(@NonNull File dir)
      Configures the working directory.
      Parameters:
      dir - the directory, must not be null
      Returns:
      this operation instance
      Throws:
      NullPointerException - if dir is null

    • workDir

      public ExecOperation workDir(@NonNull Path dir)
      Configures the working directory.
      Parameters:
      dir - the directory, must not be null
      Returns:
      this operation instance
      Throws:
      NullPointerException - if dir is null

    • workDir

      public ExecOperation workDir(@NonNull String dir)
      Configures the working directory.
      Parameters:
      dir - the directory path, must not be null or empty
      Returns:
      this operation instance
      Throws:
      IllegalArgumentException - if dir is null or empty

    • workDir

      public File workDir()
      Returns the working directory.
      Returns:
      the directory, or null if not yet configured via fromProject(BaseProject) or workDir(File)