Package rife.bld.extension

Class JBangOperation

java.lang.Object
rife.bld.operations.AbstractOperation<JBangOperation>
rife.bld.extension.JBangOperation
@NullMarked public class JBangOperation extends AbstractOperation<JBangOperation>
Run JBang with the specified arguments.
Since:
1.0
Author:
Erik C. Thauvin

  • Constructor Details

    • JBangOperation

      public JBangOperation()

  • Method Details

    • execute

      public void execute() throws Exception
      Performs the operation
      Specified by:
      execute in class AbstractOperation<JBangOperation>
      Throws:
      Exception - if an error occurs
      ExitStatusException - if workDir is null or invalid, execution fails or times out

    • 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:
      • SystemTools.isAix()

    • 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:
      • SystemTools.isCygwin()

    • 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:
      • SystemTools.isFreeBsd()

    • isLinux

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

    • isMacOS

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

    • 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:
      • SystemTools.isMinGw()

    • 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:
      • SystemTools.isOpenVms()

    • 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:
      • SystemTools.isSolaris()

    • 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:
      • SystemTools.isWindows()

    • args

      public JBangOperation args(Collection<String> args)
      Sets the arguments to be used in the script.
      Parameters:
      args - the arguments to use in the script
      Returns:
      this operation instance
      Throws:
      NullPointerException - if the args is null or contains null elements
      IllegalArgumentException - if the args is empty, or contains empty elements

    • args

      public JBangOperation args(String... args)
      Sets the arguments to be used in the script.
      Parameters:
      args - the arguments to use in the script
      Returns:
      this operation instance
      Throws:
      NullPointerException - if the args is null or contains null elements
      IllegalArgumentException - if the args is empty, or contains empty elements

    • args

      public List<String> args()
      Retrieves the live collection of arguments to be passed to the script.

      The returned list is the operation's internal list. Callers may add to it directly; this is intentional by design (builder pattern).

      Returns:
      the mutable list of script arguments

    • env

      public JBangOperation env(String name, String value)
      Adds an environment variable.

      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:
      IllegalArgumentException - if name is blank
      NullPointerException - if name or value is null
      See Also:

    • env

      public JBangOperation env(Map<String,String> vars)
      Adds environment variables.

      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 and must not contain null keys or values
      Returns:
      this operation instance
      Throws:
      NullPointerException - if vars is null, or if vars contains a null key or value
      See Also:

    • env

      public Map<String,String> env()
      Returns the environment variables.

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

      Returns:
      the mutable environment variables map, never null

    • exitOnFailure

      public JBangOperation exitOnFailure(boolean exitOnFailure)
      Configures whether the operation should exit upon a JBang execution failure.

      Default value is true

      Parameters:
      exitOnFailure - true if the operation should exit on failure, false otherwise
      Returns:
      this operation instance

    • fromProject

      public JBangOperation fromProject(BaseProject project)
      Configures a JBang operation from a BaseProject.

      Sets the following from the project:

      • workDir to the project's directory, if not already set
      • jBangHome to the JBANG_HOME environment variable, if not already set. A caller-set value always takes precedence over the environment variable.
      Parameters:
      project - the project to configure the operation from
      Returns:
      this operation instance
      Throws:
      NullPointerException - if the project is null

    • inheritIO

      public JBangOperation 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

    • isExitOnFailure

      public boolean isExitOnFailure()
      Checks whether the operation is configured to exit upon a JBang execution failure.

      Default value is true

      Returns:
      true if the operation is set to exit on failure, false otherwise.

    • 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 stderr is redirected to stdout
      See Also:

    • jBangArgs

      public JBangOperation jBangArgs(Collection<String> args)
      Sets the arguments to be used when running the script
      Parameters:
      args - the arguments to use when running the script
      Returns:
      this operation instance
      Throws:
      NullPointerException - if the args is null or contains null elements
      IllegalArgumentException - if the args is empty, or contains empty elements

    • jBangArgs

      public JBangOperation jBangArgs(String... args)
      Sets one or more arguments to be used when running the script.
      Parameters:
      args - the arguments to use when running the script
      Returns:
      this operation instance
      Throws:
      NullPointerException - if the args is null or contains null elements
      IllegalArgumentException - if the args is empty, or contains empty elements

    • jBangArgs

      public List<String> jBangArgs()
      Retrieves the live collection of arguments to be used when running the script.

      The returned list is the operation's internal list. Callers may add to it directly; this is intentional by design (builder pattern).

      Returns:
      the mutable list of JBang arguments

    • jBangHome

      public JBangOperation jBangHome(String jBangHome)
      Sets the JBang home directory.
      Parameters:
      jBangHome - the JBang home directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if jBangHome is null
      IllegalArgumentException - if jBangHome is blank

    • jBangHome

      public JBangOperation jBangHome(File jBangHome)
      Sets the JBang home directory.
      Parameters:
      jBangHome - the JBang home directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if jBangHome is null

    • jBangHome

      public JBangOperation jBangHome(Path jBangHome)
      Sets the JBang home directory.
      Parameters:
      jBangHome - the JBang home directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if jBangHome is null

    • jBangHome

      public @Nullable File jBangHome()
      Retrieves the JBang home directory.
      Returns:
      the JBang home directory

    • outputConsumer

      public JBangOperation outputConsumer(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

    • reset

      public void reset()
      Resets the script-related state of the operation to its default values.

      Specifically, this method:

      The following are intentionally preserved across resets, as they are typically set once via fromProject and shared across multiple script executions: workDir, jBangHome, timeout, inheritIO, and the outputConsumer.

    • script

      public JBangOperation script(String script)
      Sets the script to be executed.
      Parameters:
      script - the script to execute
      Returns:
      this operation instance
      Throws:
      NullPointerException - if script is null
      IllegalArgumentException - if script is blank

    • script

      public @Nullable String script()
      Retrieves the script that has been set for execution.
      Returns:
      the script to be executed or null

    • timeout

      public JBangOperation timeout(long seconds)
      Sets the timeout for JBang execution in seconds.

      If the process does not complete within the specified timeout, it will be terminated and the operation will fail. If set to any negative value, the process will wait indefinitely. Passing 0 is not allowed; use a negative value to indicate no timeout.

      Default is 600 seconds (10 minutes)

      Parameters:
      seconds - the timeout in seconds (positive); use a negative value for no timeout
      Returns:
      this operation instance
      Throws:
      IllegalArgumentException - if seconds is 0
      Since:
      1.2

    • timeout

      public long timeout()
      Retrieves the timeout for JBang execution in seconds.

      A positive value is the timeout duration in seconds. A negative value indicates no timeout (wait indefinitely). 0 is not a valid state; the setter disallows it.

      Returns:
      the timeout in seconds (positive), or a negative value if no timeout is set
      Since:
      1.2

    • workDir

      public @Nullable File workDir()
      Retrieves the working directory.
      Returns:
      the directory

    • workDir

      public JBangOperation workDir(File dir)
      Provides the working directory if it differs from the project's directory.
      Parameters:
      dir - the directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if dir is null

    • workDir

      public JBangOperation workDir(Path dir)
      Provides the working directory if it differs from the project's directory.
      Parameters:
      dir - the directory
      Returns:
      this operation instance
      Throws:
      NullPointerException - if dir is null

    • workDir

      public JBangOperation workDir(String dir)
      Provides the working directory if it differs from the project's directory.
      Parameters:
      dir - the directory path
      Returns:
      this operation instance
      Throws:
      IllegalArgumentException - if dir is blank
      NullPointerException - if dir is null