flux
Interface FlowContext

All Superinterfaces:

AuditTrailFlowContext, java.io.Serializable, VariableManager

All Known Subinterfaces:

KeyFlowContext

public interface FlowContext
extends AuditTrailFlowContext

Provides information about a particular flow of execution in a flow chart.

Author:

Copyright 2014 Flux Corporation. All rights reserved.

Method Summary

java.sql.Connection	getDatabaseConnection() Returns a database connection for an action's use during execution.
ErrorResult	getErrorResult() Returns status information from the last time an exception was thrown while this flow context was executing a flow chart.
long	getId() Returns the flow context ID.
Logger	getLogger() Returns the Flow Chart Logger, which flow charts use to log messages.
java.util.SortedSet<java.lang.String>	getRaisedSignals() Returns all signals that have been raised on the current action.
java.sql.Connection	getRawDatabaseConnection() Returns a database connection for an action's use during execution.
java.lang.String	getStatus() Returns the status message for this flow context, which is an optional natural language description that describes the state of this flow context within the scope of its enveloping flow chart.
boolean	isExpedited() Indicates whether this flow of execution was expedited.
boolean	isInterrupted() Returns true if execution has been interrupted by a call to Engine.interrupt().
boolean	isSignalRaised(java.lang.String signal) Indicates whether the specified signal has been raised on the current action.
boolean	isTimedOut() Indicates whether the current action has timed out.
boolean	isTransient(java.lang.String name) Indicates if the specified variable name is transient.
void	putTransient(java.lang.String name, java.lang.Object variable) Adds a transient variable to the flow context's variable manager, which will not be persisted to the database.
void	returnTransient() Indicates that the return value from the execute() method should be treated as a transient variable, which will not be stored to the database and will be purged at the next transaction break.
void	returnTransient(boolean enabled) Sets whether the return value from the execute() method should be treated as a transient variable, which will not be stored to the database and will be purged at the next transaction break.
void	sendToAuditTrail(java.lang.String eventName, java.lang.String eventMessage) Publishes an audit trail event using the given name and message.
void	setStatus(java.lang.String statusMessage) Sets the status message for this flow context, which is an optional natural language description that describes the state of this flow context within the scope of its enveloping flow chart.
java.lang.String	substitute(java.lang.String value) Performs variable substitution on a string that may contain Flux variable substitution expressions.
boolean	willReturnTransient() Indicates whether the return value from the execute() method will be treated as a transient variable, which will not be stored to the database and will be purged at the next transaction break.

Methods inherited from interface flux.audittrail.AuditTrailFlowContext

getActionName, getEngine, getFlowChart, getLastResult, getUsername

Methods inherited from interface flux.VariableManager

clear, contains, get, getNames, put, put, put, put, put, put, put, put, put, putAll, remove, size

Method Detail

getDatabaseConnection

java.sql.Connection getDatabaseConnection()

Returns a database connection for an action's use during execution. PreparedStatement and ResultSet objects created from this connection do not need to be closed. The engine closes them automatically. The returned database connection is "wrapped" so that database resources, such as prepared statements and result sets, do not need to be closed explicitly.

This database connection wrapper throws exceptions from methods that are not "wrapped", including createStatement() and close(). If you require the use of createStatement() or other unwrapped methods, contact Flux technical support at support@flux.ly +1 (720) 441-1844.

Use getRawDatabaseConnection() to retrieve an "unwrapped", or raw, database connection.

Returns:

A database connection.

See Also:

getRawDatabaseConnection()

getErrorResult

ErrorResult getErrorResult()

Returns status information from the last time an exception was thrown while this flow context was executing a flow chart. If no exception has been thrown, this method returns null.

Returns:

Status information from the last time an exception was thrown while this flow context was executing a flow chart.

getId

long getId()

Returns the flow context ID.

Returns:

The flow context ID.

getLogger

Logger getLogger()

Returns the Flow Chart Logger, which flow charts use to log messages.

Returns:

The Flow Chart Logger, which flow charts use to log messages.

getRaisedSignals

java.util.SortedSet<java.lang.String> getRaisedSignals()
                                                       throws EngineException

Returns all signals that have been raised on the current action.

Returns:

All signals that have been raised on the current action.

Throws:

EngineException - If a system error occurs.

getRawDatabaseConnection

java.sql.Connection getRawDatabaseConnection()

Returns a database connection for an action's use during execution. This database connection is not "wrapped" by the engine. If this unwrapped database connection is used to create statements, prepared statements, result sets, etc, they must be closed explicitly. The returned database connection comes straight from the JDBC driver or data source.

Do not call close() on this raw database connection. If you do, your flow chart will fail.

Use getDatabaseConnection() to retrieve a "wrapped" database connection.

Returns:

A raw, unwrapped database connection.

See Also:

getDatabaseConnection()

getStatus

java.lang.String getStatus()
                           throws EngineException

Returns the status message for this flow context, which is an optional natural language description that describes the state of this flow context within the scope of its enveloping flow chart.

The status message appears in the "message" column of the flow chart listing in the Operations Console and can also be obtained through FlowChartElement. Using this method, actions can provide useful messages to operators such as status updates.

As an example, the status of the flow chart can be recorded using the setMessage() method with a message like the following:

The dailyBatch.ech file was not available from client. Waiting for file to become available.

Returns:

The status message for this flow context.

Throws:

EngineException - If a system error occurs.

isExpedited

boolean isExpedited()

Indicates whether this flow of execution was expedited. Once expedited, a flow of execution eventually runs and remains expedited until the current action finishes executing.

Returns:

Whether this flow of execution was expedited.

See Also:

Engine.expedite(String namespace)

isInterrupted

boolean isInterrupted()

Returns true if execution has been interrupted by a call to Engine.interrupt(). It is up to the action itself to stop executing, in much the same way Thread.interrupt() and Thread.isInterrupted() behave. Regardless, the engine will rollback the transaction of an interrupted flow when the flow is not executing an action.

Returns:

true If this flow was interrupted, else false.

isSignalRaised

boolean isSignalRaised(java.lang.String signal)
                       throws EngineException

Indicates whether the specified signal has been raised on the current action.

Parameters:

signal - The signal of interest.

Returns:

Whether the specified signal has been raised on the current action.

Throws:

EngineException - If a system error occurs.

See Also:

Action.setSignalsToMonitor(java.util.Set)

isTimedOut

boolean isTimedOut()
                   throws EngineException

Indicates whether the current action has timed out. When an action (but not a trigger) receives a timeout signal, it is up to the action itself to stop executing, in much the same way Thread.interrupt() and Thread.isInterrupted() behave. This method is equivalent to calling isSignalRaised("timeout(action name)"), where action name is the name of the the current action.

Returns:

Whether the current action has timed out.

Throws:

EngineException - If a system error occurs.

isTransient

boolean isTransient(java.lang.String name)

Indicates if the specified variable name is transient. A transient variable in a flow context's variable manager will not be persisted to the database. Transient variables are cleared at transaction breaks.

If transient variables were not cleared at transaction breaks, then flow chart behavior could be inconsistent. For example, if the computer crashes, transient variables would be lost. Subsequent flow chart triggers and actions, which depend on the existence of those transient variables, would not behave correctly in this case. Therefore, for consistent flow chart behavior in the face of computer crashes, transient variables are cleared at transaction breaks.

Parameters:

name - The name of a flow context variable.

Returns:

Whether the specified variable is transient.

Throws:

java.lang.IllegalArgumentException - If the specified flow context variable does not exist.

See Also:

putTransient(String, Object)

putTransient

void putTransient(java.lang.String name,
                  java.lang.Object variable)

Adds a transient variable to the flow context's variable manager, which will not be persisted to the database. Transient variables are cleared at transaction breaks.

If transient variables were not cleared at transaction breaks, then flow chart behavior could be inconsistent. For example, if the computer crashes, transient variables would be lost. Subsequent flow chart triggers and actions, which depend on the existence of those transient variables, would not behave correctly in this case. Therefore, for consistent flow chart behavior in the face of computer crashes, transient variables are cleared at transaction breaks.

Parameters:

name - The name of the transient variable.

variable - The transient variable.

See Also:

isTransient(String), VariableManager.put(java.lang.String, boolean)

returnTransient

void returnTransient()

Indicates that the return value from the execute() method should be treated as a transient variable, which will not be stored to the database and will be purged at the next transaction break.

returnTransient

void returnTransient(boolean enabled)

Sets whether the return value from the execute() method should be treated as a transient variable, which will not be stored to the database and will be purged at the next transaction break.

Parameters:

enabled - Whether the return value from the execute() method should be treated as a transient variable

sendToAuditTrail

void sendToAuditTrail(java.lang.String eventName,
                      java.lang.String eventMessage)

Publishes an audit trail event using the given name and message. Using this method, actions can provide updates on their execution status to the audit trail. These updates are entirely optional and not all actions provide such updates.

All audit trail events are saved with the current time as well as other useful status information. For information on how to react to an audit trail event from a flow chart, see flux.AuditTrailTrigger.

Multiple events can be sent to the audit trail by calling this method several times in succession.

As an example, a failure in a Java Action can be reported to the audit trail using the sendToAuditTrail() method with an event name like "File Transfer Termination" and an event message like "Unable to find incoming file 'foo.txt' for company 'Bar Corporation'".

Parameters:

eventName - The name of the audit trail event to be published.

eventMessage - The accompanying message for the audit trail event to be published.

See Also:

AuditTrailTrigger

setStatus

void setStatus(java.lang.String statusMessage)

Sets the status message for this flow context, which is an optional natural language description that describes the state of this flow context within the scope of its enveloping flow chart.

The status message appears in the "message" column of the flow chart listing in the Operations Console and can also be obtained through FlowChartElement. Using this method, actions can provide useful messages to operators such as status updates.

As an example, the status of the flow chart can be recorded using the setMessage() method with a message like the following:

The dailyBatch.ech file was not available from client. Waiting for file to become available.

Parameters:

statusMessage - The status message for this flow context.

substitute

java.lang.String substitute(java.lang.String value)
                            throws EngineException

Performs variable substitution on a string that may contain Flux variable substitution expressions. Any variables referenced in the string will be evaluated using the flow context, current action, and flow chart variable managers.

See the "Substitution" section of the Flux manual for more information on variable substitution expressions and how they are evaluated.

Parameters:

value - The string on which to perform variable substitution.

Returns:

The original string with variable substitution expressions evaluated.

Throws:

EngineException - If an error occurs while substituting the given string.

willReturnTransient

boolean willReturnTransient()

Indicates whether the return value from the execute() method will be treated as a transient variable, which will not be stored to the database and will be purged at the next transaction break.

By default, return values from the execute() method are not transient.

Returns:

Whether the return value from the execute() method will be treated as a transient variable.