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.

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.