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
RESULTresultintThe process's exit code, as returned by the operating system, if the process executed synchronously.
RESULTstderrjava.lang.StringThe standard error (stderr) from the completed process, if the process executed synchronously.
RESULTstdoutjava.lang.StringThe standard output (stdout) from the completed process, if the process executed synchronously.

Author:
Copyright 2014 Flux Corporation. All rights reserved.

Nested Class Summary
static class ProcessAction.ProcessActionResult
          The result when a process finishes executing.
 
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
 
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.


© 2014 Flux Corporation. All rights reserved.