ProcessAction (Flux Javadoc. Version 8.2. Released on 31 October 2022.)

All Superinterfaces:: Action, AgentAction, java.lang.Cloneable, RuntimeDataMap, java.io.Serializable

public interface ProcessAction
extends Action, AgentAction

Executes a native process or command line program. By default, this process action blocks until the process finishes. The process's exit code is returned in the flow context using a ProcessActionResult object.

Optionally, if the flow chart is interrupted, the process is destroyed.

Furthermore, the process can be configured to run in the background, in which case interrupting the flow chart does not destroy the process nor is the exit code returned.

Finally, if a process action is executed on an agent, there is an implicit transaction break on that process action. This implicit transaction break allows a very large number of processes to execute on agents.

The Process Action returns its result in the flow context variable "RESULT". The following table contains more information on accessing and using the result.

Flow Context Variable	Field	Java Type	Description
RESULT	result	int	The process's exit code, as returned by the operating system, if the process executed synchronously.
RESULT	stderr	java.lang.String	The standard error (stderr) from the completed process, if the process executed synchronously.
RESULT	stdout	java.lang.String	The standard output (stdout) from the completed process, if the process executed synchronously.

Author:: Copyright 2000-2025 Flux Corporation. All rights reserved.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class ProcessAction.ProcessActionResult
The result when a process finishes executing.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`ProcessAction.ProcessActionResult` The result when a process finishes executing.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`java.util.List<java.lang.String>`	`getArguments()` Returns command line arguments for the native process.
`boolean`	`getAsynchronous()` Returns whether the native process runs asynchronously, in the background.
`java.lang.String`	`getCommand()` Returns the command line for the native process.
`java.util.Properties`	`getCommandProperties()` Returns substitution properties that are referenced by the process command line.
`boolean`	`getDestroyOnInterrupt()` Returns whether this process is destroyed if the current flow chart is interrupted.
`boolean`	`getDestroyOnSignal()` Returns whether this process is destroyed if this process action receives a signal.
`boolean`	`getDestroyOnTimeout()` Returns whether this process is destroyed if this process takes too long to execute.
`java.util.Properties`	`getEnvironment()` Returns the environment properties used by the native process.
`java.lang.String`	`getErrorCondition()` Returns the expression that is tested to detect whether a process failed.
`java.lang.String`	`getStderrFile()` Returns the file name where the process's stderr (standard error) is redirected, if not otherwise set on the command line.
`java.lang.String`	`getStdinFile()` Returns the file name where the process's stdin (standard in) is redirected, if not otherwise set on the command line.
`java.lang.String`	`getStdoutFile()` Returns the file name where the process's stdout (standard out) is redirected, if not otherwise set on the command line.
`java.lang.String`	`getWorkingDirectory()` Returns the starting directory where the native process runs.
`boolean`	`isAppendToOutputFile()` Indicates whether this process's output is written to the end of the configured stdout and stderr files, if not otherwise set on the command line.
`void`	`setAppendToOutputFile(boolean enabled)` Sets whether this process's output is written to the end of the configured stdout and stderr files, if not otherwise set on the command line.
`void`	`setArguments(java.util.List arguments)` Sets command line arguments for the native process.
`void`	`setAsynchronous(boolean asynchronous)` Sets whether the native process runs asynchronously, in the background.
`void`	`setCommand(java.lang.String command)` Sets the command line for the native process.
`void`	`setCommandProperties(java.util.Properties commandProperties)` Sets substitution properties that are referenced by the process command line.
`void`	`setDestroyOnInterrupt(boolean destroyOnInterrupt)` Sets whether this process is destroyed if the current flow chart is interrupted.
`void`	`setDestroyOnSignal(boolean destroyOnSignal)` Sets whether this process is destroyed if this process action receives a signal.
`void`	`setDestroyOnTimeout(boolean destroyOnTimeout)` Sets whether this process is destroyed if this process takes too long to execute.
`void`	`setEnvironment(java.util.Properties environment)` Sets the environment properties used by the native process.
`void`	`setErrorCondition(java.lang.String errorCondition)` Sets the expression that is tested to detect whether a process failed.
`void`	`setStderrFile(java.lang.String stderr)` Sets the file name where the process's stderr (standard error) is redirected, if not otherwise set on the command line.
`void`	`setStdinFile(java.lang.String stdin)` Sets the file name where the process's stdin (standard in) is redirected, if not otherwise set on the command line.
`void`	`setStdoutFile(java.lang.String stdout)` Sets the file name where the process's stdout (standard out) is redirected, if not otherwise set on the command line.
`void`	`setWorkingDirectory(java.lang.String startingDirectory)` Sets the starting directory where the native process runs.

Methods inherited from interface flux.Action
addFlow, addFlow, addSignalFlow, clone, execute, getDescription, getFlows, getHiddenVariableNames, getJoinExpression, getName, getPostscript, getPostscriptLanguage, getPrescript, getPrescriptLanguage, getResultInfo, getSignalsToMonitor, getTimeoutBusinessInterval, getTimeoutBusinessIntervalNamespace, getTimeoutExpression, getVariableManager, isEndOfRun, isJoinPoint, isSkippable, isStartAction, isStartOfRun, isTransactionBreak, removeFlow, reset, setDescription, setElseFlow, setEndOfRun, setErrorFlow, setErrorFlowWithoutRollback, setErrorFlowWithRollback, setJoinExpression, setJoinPoint, setName, setPostscript, setPostscriptLanguage, setPrescript, setPrescriptLanguage, setSignalsToMonitor, setSkippable, setStartAction, setStartOfRun, setTimeoutBusinessInterval, setTimeoutBusinessIntervalNamespace, setTimeoutExpression, setTimeoutFlow, setTransactionBreak, verify, verifyOnClient

Methods inherited from interface flux.runtimedatamap.RuntimeDataMap
getRuntimeDataMap, setRuntimeDataMap

Methods inherited from interface flux.agent.AgentAction
getAgentPool, setAgentPool

- Method Detail
  - isAppendToOutputFile
```
boolean isAppendToOutputFile()
```
    Indicates whether this process's output is written to the end of the configured stdout and stderr files, if not otherwise set on the command line. By default, this property is false, and this process clears the configured stdout and stderr output files before writing to them. This property has no effect unless the stdoutFile or stderrFile properties are set.
    
    Returns:
    
    Whether this process's output is written to the end of the configured stdout and stderr files.
  - getArguments
```
java.util.List<java.lang.String> getArguments()
```
    Returns command line arguments for the native process. If there are any command line arguments listed within the command line itself, these arguments are appended to those pre-existing command line arguments.
    
    Returns:
    
    Command line arguments for the native process.
  - getAsynchronous
```
boolean getAsynchronous()
```
    Returns whether the native process runs asynchronously, in the background. By default, processes run synchronously, in the foreground. If marked as asynchronous, some additional resources are created and are not destroyed until the native process exits. To avoid this extra resource usage with background processes, run this process action in the foreground, execute a command prompt or shell as the process, and instruct the command prompt or shell to run the command in the background. On Windows, "cmd.exe /c start myprogram.exe" will run "myprogram.exe" in the background. Similarly, on Unix, the "&" symbol can be used in shell scripts to execute commands in the background.
    Background processes do not prevent the JVM from exiting. When run in the background, some native processes will still exit when the JVM exits, due to failed interactions between a native process and the JVM, which takes over standard I/O for forked processes.
    
    Returns:
    
    Whether the native process runs asynchronously, in the background.
  - getCommand
```
java.lang.String getCommand()
```
    Returns the command line for the native process. If the command contains the symbol "${my property}", then the command property called "my property" is substituted for "${my property}" before the command is executed. These command properties are available via the getCommandProperties() and setCommandProperties() methods.
    
    Returns:
    
    The command line for the native process.
    
    See Also:
    
    getCommandProperties(), setCommandProperties(java.util.Properties)
  - getCommandProperties
```
java.util.Properties getCommandProperties()
```
    Returns substitution properties that are referenced by the process command line.
    
    Returns:
    
    Substitution properties that are referenced by the process command line.
    
    See Also:
    
    getCommand(), setCommand(java.lang.String)
  - getDestroyOnInterrupt
```
boolean getDestroyOnInterrupt()
```
    Returns whether this process is destroyed if the current flow chart is interrupted. By default, it is not destroyed. This property can be used only if the process is run synchronously.
    
    Returns:
    
    Whether this process is destroyed if the current flow chart is interrupted.
  - getDestroyOnSignal
```
boolean getDestroyOnSignal()
```
    Returns whether this process is destroyed if this process action receives a signal. By default, it is not destroyed. This property can be used only if the process is run synchronously. Note that if this process action times out, it is destroyed only if the destroy-on-timeout property is enabled, regardless of the setting of this property.
    
    Returns:
    
    Whether this process is destroyed if this process action receives a signal.
  - getDestroyOnTimeout
```
boolean getDestroyOnTimeout()
```
    Returns whether this process is destroyed if this process takes too long to execute. This property is consulted only if this process is run synchronously. By default, this process is not destroyed.
    
    Returns:
    
    Whether this process is destroyed if this process takes too long to execute.
  - getEnvironment
```
java.util.Properties getEnvironment()
```
    Returns the environment properties used by the native process.
    Note that leaving the environment at its default setting of null may pass the environment of the Flux engine's JVM to the process. However, if the environment is set, it is possible that none of the Flux engine's JVM environment properties are passed to the process. In that case, additional environment properties may need to be set explicitly. The exact behavior depends on the specific JVM and operating system.
    For example, the Windows command processor and other Windows programs need the "SystemRoot" property to be set in order to run correctly. Typically, this property is set to "c:\windows".
    
    Returns:
    
    The environment properties used by the native process.
  - getErrorCondition
```
java.lang.String getErrorCondition()
```
    Returns the expression that is tested to detect whether a process failed. The syntax for error conditions is contained in the Flux Manual. It is similar to an SQL "where" clause.
    If a process fails, an exception is thrown, thereby forcing the execution of the flow chart to enter Flux's standard error handling mechanisms.
    By default, the error condition is undefined, which means that a process is never deemed to have failed and this process action does not throw an exception after a process executes.
    If an error condition has been set, after the process returns its result, the error condition is evaluated using that result. If the error condition is then satisfied (found to be true), an exception is thrown. Otherwise, no exception is thrown.
    As an example of an error condition that causes an exception to the thrown if the process's exit code is not zero, use the syntax "RESULT <> 0".
    This property is ignored if the Process Action is configured to run asynchronously.
    
    Returns:
    
    The expression that is tested to detect whether a process failed. A null or empty error condition indicates that the error condition is undefined.
    
    See Also:
    
    getAsynchronous(), setAsynchronous(boolean)
  - getStderrFile
```
java.lang.String getStderrFile()
```
    Returns the file name where the process's stderr (standard error) is redirected, if not otherwise set on the command line.
    
    Returns:
    
    The file name where the process's stderr redirected.
  - getStdinFile
```
java.lang.String getStdinFile()
```
    Returns the file name where the process's stdin (standard in) is redirected, if not otherwise set on the command line.
    
    Returns:
    
    The file name where the process's stdin redirected.
  - getStdoutFile
```
java.lang.String getStdoutFile()
```
    Returns the file name where the process's stdout (standard out) is redirected, if not otherwise set on the command line.
    
    Returns:
    
    The file name where the process's stdout is redirected.
  - getWorkingDirectory
```
java.lang.String getWorkingDirectory()
```
    Returns the starting directory where the native process runs. By default, the current working directory (the "user.dir" system property) is used.
    
    Returns:
    
    The starting directory where the native process runs.
  - setAppendToOutputFile
```
void setAppendToOutputFile(boolean enabled)
```
    Sets whether this process's output is written to the end of the configured stdout and stderr files, if not otherwise set on the command line. If this property is false, this process clears the configured stdout and stderr output files before writing to them. This property has no effect unless the stdoutFile or stderrFile properties are set.
    
    Parameters:
    
    enabled - Whether this process's output is written to the end of the configured stdout and stderr files.
  - setArguments
```
void setArguments(java.util.List arguments)
```
    Sets command line arguments for the native process. If there are any command line arguments listed within the command line itself, these arguments are appended to those pre-existing command line arguments. Sets the command arguments for the native process.
    
    Parameters:
    
    arguments - Command line arguments for the native process.
  - setAsynchronous
```
void setAsynchronous(boolean asynchronous)
```
    Sets whether the native process runs asynchronously, in the background. By default, processes run synchronously, in the foreground. If marked as asynchronous, some additional resources are created and are not destroyed until the native process exits. To avoid this extra resource usage with background processes, run this process action in the foreground, execute a command prompt or shell as the process, and instruct the command prompt or shell to run the command in the background. On Windows, "cmd.exe /c start myprogram.exe" will run "myprogram.exe" in the background. Similarly, on Unix, the "&" symbol can be used in shell scripts to execute commands in the background.
    Background processes do not prevent the JVM from exiting. When run in the background, some native processes will still exit when the JVM exits, due to failed interactions between a native process and the JVM, which takes over standard I/O for forked processes.
    
    Parameters:
    
    asynchronous - Whether the native process runs asynchronously, in the background.
  - setCommand
```
void setCommand(java.lang.String command)
```
    Sets the command line for the native process. If the command contains the symbol "${my property}", then the command property called "my property" is substituted for "${my property}" before the command is executed. These command properties are available via the getCommandProperties() and setCommandProperties() methods.
    
    Parameters:
    
    command - The command line for the native process.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the command is null or empty.
    
    See Also:
    
    getCommandProperties(), setCommandProperties(java.util.Properties)
  - setCommandProperties
```
void setCommandProperties(java.util.Properties commandProperties)
```
    Sets substitution properties that are referenced by the process command line.
    
    Parameters:
    
    commandProperties - Substitution properties that are referenced by the process command line.
    
    See Also:
    
    getCommand(), setCommand(java.lang.String)
  - setDestroyOnInterrupt
```
void setDestroyOnInterrupt(boolean destroyOnInterrupt)
```
    Sets whether this process is destroyed if the current flow chart is interrupted. This property can be used only if the process is run synchronously.
    
    Parameters:
    
    destroyOnInterrupt - Whether this process is destroyed if the current flow chart is interrupted.
  - setDestroyOnSignal
```
void setDestroyOnSignal(boolean destroyOnSignal)
```
    Sets whether this process is destroyed if this process action receives a signal. This property can be used only if the process is run synchronously. Note that if this process action times out, it is destroyed only if the destroy-on-timeout property is enabled, regardless of the setting of this property.
    
    Parameters:
    
    destroyOnSignal - Whether this process is destroyed if this process action receives a signal.
  - setDestroyOnTimeout
```
void setDestroyOnTimeout(boolean destroyOnTimeout)
```
    Sets whether this process is destroyed if this process takes too long to execute. This property is consulted only if this process is run synchronously.
    
    Parameters:
    
    destroyOnTimeout - Whether this process is destroyed if this process takes too long to execute.
  - setEnvironment
```
void setEnvironment(java.util.Properties environment)
```
    Sets the environment properties used by the native process.
    Note that leaving the environment at its default setting of null may pass the environment of the Flux engine's JVM to the process. However, if the environment is set, it is possible that none of the Flux engine's JVM environment properties are passed to the process. In that case, additional environment properties may need to be set explicitly. The exact behavior depends on the specific JVM and operating system.
    For example, the Windows command processor and other Windows programs need the "SystemRoot" property to be set in order to run correctly. Typically, this property is set to "c:\windows".
    
    Parameters:
    
    environment - The environment used by the native process.
  - setErrorCondition
```
void setErrorCondition(java.lang.String errorCondition)
```
    Sets the expression that is tested to detect whether a process failed. The syntax for error conditions is contained in the Flux Manual. It is similar to an SQL "where" clause.
    If a process fails, an exception is thrown, thereby forcing the execution of the flow chart to enter Flux's standard error handling mechanisms.
    By default, the error condition is undefined, which means that a process is never deemed to have failed and this process action does not throw an exception after a process executes.
    If an error condition has been set, after the process returns its result, the error condition is evaluated using that result. If the error condition is then satisfied (found to be true), an exception is thrown. Otherwise, no exception is thrown.
    As an example of an error condition that causes an exception to the thrown if the process's exit code is not zero, use the syntax "RESULT <> 0".
    This property is ignored if the Process Action is configured to run asynchronously.
    
    Parameters:
    
    errorCondition - The expression that is tested to detect whether a process failed. A null or empty error condition indicates that the error condition is undefined.
    
    See Also:
    
    getAsynchronous(), setAsynchronous(boolean)
  - setStderrFile
```
void setStderrFile(java.lang.String stderr)
```
    Sets the file name where the process's stderr (standard error) is redirected, if not otherwise set on the command line.
    
    Parameters:
    
    stderr - The file name where the process's stderr redirected.
  - setStdinFile
```
void setStdinFile(java.lang.String stdin)
```
    Sets the file name where the process's stdin (standard in) is redirected, if not otherwise set on the command line.
    
    Parameters:
    
    stdin - The file name where the process's stdin redirected.
  - setStdoutFile
```
void setStdoutFile(java.lang.String stdout)
```
    Sets the file name where the process's stdout (standard out) is redirected, if not otherwise set on the command line.
    
    Parameters:
    
    stdout - The file name where the process's stdout is redirected.
  - setWorkingDirectory
```
void setWorkingDirectory(java.lang.String startingDirectory)
```
    Sets the starting directory where the native process runs. By default, the current working directory (the "user.dir" system property) is used.
    
    Parameters:
    
    startingDirectory - The starting directory where the native process runs.

Interface ProcessAction

Nested Class Summary

Method Summary

Methods inherited from interface flux.Action

Methods inherited from interface flux.runtimedatamap.RuntimeDataMap

Methods inherited from interface flux.agent.AgentAction

Method Detail

isAppendToOutputFile

getArguments

getAsynchronous

getCommand

getCommandProperties

getDestroyOnInterrupt

getDestroyOnSignal

getDestroyOnTimeout

getEnvironment

getErrorCondition

getStderrFile

getStdinFile

getStdoutFile

getWorkingDirectory

setAppendToOutputFile

setArguments

setAsynchronous

setCommand

setCommandProperties

setDestroyOnInterrupt

setDestroyOnSignal

setDestroyOnTimeout

setEnvironment

setErrorCondition

setStderrFile

setStdinFile

setStdoutFile

setWorkingDirectory