flux
Interface ProcessAction
- 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 2014 Flux Corporation. All rights reserved.
Method Summary |
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 |
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.
© 2014 Flux Corporation. All rights reserved.