Package rife.bld.extension

Class JBangOperation

java.lang.Object
rife.bld.operations.AbstractOperation<JBangOperation>
rife.bld.extension.JBangOperation
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, JBang 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(@NonNull 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:
      IllegalArgumentException - if the args elements are null or empty
      NullPointerException - if the args collection is null

    • args

      public JBangOperation args(@NonNull 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:
      IllegalArgumentException - if the args elements are null or empty
      NullPointerException - if the args collection is null

    • 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(@NonNull String name, @NonNull 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 empty or null
      NullPointerException - if value is null
      See Also:

    • env

      public JBangOperation env(@NonNull 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(@NonNull 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(@NonNull 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:
      IllegalArgumentException - if the args elements are null or empty
      NullPointerException - if the args collection is null

    • jBangArgs

      public JBangOperation jBangArgs(@NonNull 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:
      IllegalArgumentException - if the args elements are null or empty
      NullPointerException - if the args collection is null

    • 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(@NonNull 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 empty

    • jBangHome

      public JBangOperation jBangHome(@NonNull 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(@NonNull 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 File jBangHome()
      Retrieves the JBang home directory.
      Returns:
      the JBang home directory

    • outputConsumer

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

    • 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(@NonNull String script)
      Sets the script to be executed.
      Parameters:
      script - the script to execute
      Returns:
      this operation instance
      Throws:
      IllegalArgumentException - if script is null or empty
      NullPointerException - if script is null

    • script

      public 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 File workDir()
      Retrieves the working directory.
      Returns:
      the directory

    • workDir

      public JBangOperation workDir(@NonNull 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(@NonNull 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(@NonNull 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 empty
      NullPointerException - if dir is null