flux
Interface Transactable

All Known Subinterfaces:

Engine, XmlEngine

public interface Transactable

Contains the engine methods that can be executed together in a single transaction.

Author:

Copyright 2000-2009 Flux Corporation. All rights reserved.

clear

long clear()
           throws EngineException,
                  java.rmi.RemoteException

Removes all flow charts, messages, publishers, users, groups, logs, audit trail entries, and, in general, all data associated with this Flux engine. Furthemore, this method resets the default administrator user account to its default settings.

Note that calling clear() from within a running job will fail, because at the next transaction break, the engine will see that the job was deleted and rollback the transaction. Rolling back the transaction will undo the work of the clear() method. A simple workaround is to fork a new thread from within the running job, have that thread call Engine.clear(), and wait for the thread to finish. This solution works because the new thread uses a new database connection to perform its work.

If a flow chart is running when clear() is called, that flow chart will not terminate until the next transaction break, at which point the flow chart's transaction will rollback and the flow chart will terminate. To force early termination, interrupt the flow chart.

Returns:

The number of flow charts that were removed.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

clearAuditTrail

void clearAuditTrail()
                     throws EngineException,
                            java.rmi.RemoteException

Removes all audit trail entries.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

clearLogs

void clearLogs()
               throws EngineException,
                      java.rmi.RemoteException

Removes all log entries from the database. Note that this method does not delete any Flux log files that may exist on the file system.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

clearRunHistory

void clearRunHistory()
                     throws EngineException,
                            java.rmi.RemoteException

Removes all run history entries.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

clearRunHistory

void clearRunHistory(java.lang.String namespace)
                     throws java.lang.IllegalArgumentException,
                            EngineException,
                            java.rmi.RemoteException

Removes all run history entries for the specified namespace.

Parameters:

namespace - The hierarchical flow chart path or absolute flow chart name. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Throws:

java.lang.IllegalArgumentException - If namespace is null or empty.

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

clearSignal

long clearSignal(java.lang.String namespace,
                 java.lang.String signal)
                 throws EngineException,
                        java.rmi.RemoteException

Clears the specified signal from all flow charts specified by a hierarchiacal flow chart namespace expression.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

signal - The name of the signal to clear.

Returns:

The number of flow charts that had the specified signal cleared.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

clearSignals

long clearSignals(java.lang.String namespace)
                  throws EngineException,
                         java.rmi.RemoteException

Clears all signals from all flow charts specified by a hierarchical flow chart namespace expression.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Returns:

The number of flow charts that had the specified signal cleared.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

expedite

long expedite(java.lang.String namespace)
              throws EngineException,
                     java.rmi.RemoteException

Forces the specified flow charts to be executed as soon as possible. If a flow chart is already running and waiting on a trigger that can be expedited, that trigger is fired as soon as possible and that flow chart continues execution. If that flow chart is not already running, it starts running as soon as possible and the first trigger encountered is fired immediately, assuming that trigger can be expedited.

Not all triggers can be expedited. If a trigger cannot be expedited, it ignores the expedite signal. Triggers that can be expedited include TimerTrigger and ManualTrigger.

Technically, when a flow chart is expedited, all flow contexts on that flow chart are expedited. For convenience, however, it is often simply said, "A flow chart is expedited" when technically it is more accurate to say, "All flow contexts on a flow chart are expedited".

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Returns:

The number of flow charts that were expedited.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

interrupt

long interrupt(java.lang.String namespace)
               throws EngineException,
                      java.rmi.RemoteException

Interrupts the specified flow charts as soon as possible. If a running job is interrupted, that job can detect whether it has been interrupted by calling FlowContext.isInterrupted(), in which case that job can terminate its work as soon as possible.

Regardless of whether FlowContext.isInterrupted() is called by a running job, calling interrupt() will only cause the engine to stop executing the job and rollback the transaction. It will not prevent the job from starting again. In this case, use Engine.pause(flowChartId) and then Engine.interrupt(flowChartId). In the same manner, if the job is supposed to stop executing and be deleted, call Engine.remove(flowChartId), then Engine.interrupt(flowChartId).

Techically, when a flow chart is interrupted, all flow contexts on that flow chart are interrupted. For convenience, however, it is often simply said, "A flow chart is interrupted" when technically it is more accurate to say, "All flow contexts on a flow chart are interrupted".

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Returns:

The number of flow charts that were interrupted.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

pause

long pause(java.lang.String namespace)
           throws EngineException,
                  java.rmi.RemoteException

Pauses all flow charts specified by a hierarchical flow chart namespace expression.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Returns:

The number of flow charts that were paused.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

raiseSignal

long raiseSignal(java.lang.String namespace,
                 java.lang.String signal)
                 throws EngineException,
                        java.rmi.RemoteException

Raises the specified signal on all flow charts specified by a hierarchiacal flow chart namespace expression.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

signal - The name of the signal to raise.

Returns:

The number of flow charts on which the specified signal was raised.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

recover

long recover(java.lang.String namespace)
             throws EngineException,
                    java.rmi.RemoteException

Restarts all flow contexts that are in the ERROR super-state and the FAILED sub-state from the beginning of the main-line (not the default error handler) flow chart transaction that led to the FAILED state.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Returns:

The number of flow contexts that were recovered.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

recover

long recover(java.lang.String namespace,
             boolean skipOffendingAction)
             throws EngineException,
                    java.rmi.RemoteException

Restarts all flow contexts that are in the ERROR super-state and the FAILED sub-state from the beginning of the main-line (not the default error handler) flow chart transaction that led to the FAILED state.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

skipOffendingAction - When true, does not re-execute the offending action that generated the error, providing the offending action is skippable.

Returns:

The number of flow contexts that were recovered.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

See Also:

Action.setSkippable(boolean)

remove

long remove(java.lang.String namespace)
            throws EngineException,
                   java.rmi.RemoteException

Removes executing flow charts from the engine. Note that calling remove() using the current job ID from within a running job will fail, because at the next transaction break, the engine will see that the job was deleted and rollback the transaction. Rolling back the transaction will undo the work of the remove() method. A simple workaround is to fork a new thread from within the running job, have that thread call Engine.remove(), and wait for the thread to finish. This solution works because the new thread uses a new database connection to perform its work.

If a job is running when remove() is called, that job will not terminate until the next transaction break, at which point the job's transaction will rollback and the job will terminate. To force early termination, interrupt the job.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Returns:

The number of flow charts that were removed.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

rename

long rename(java.lang.String oldNamespace,
            java.lang.String newNamespace)
            throws EngineException,
                   java.rmi.RemoteException

Renames all flow charts in the old namespace to the new namespace. In effect, a textual substitution is performed on each flow chart in the old namespace so that within each flow chart name, the old namespace string is replaced by the new namespace string.

Parameters:

oldNamespace - The namespace to be renamed.

newNamespace - The target namespace.

Returns:

The number of flow charts that were renamed.

Throws:

EngineException - If either namespace is null or empty, both namespaces are equal, or a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

resume

long resume(java.lang.String namespace)
            throws EngineException,
                   java.rmi.RemoteException

Resumes all flow charts specified by the hierarchical flow chart namespace expression. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace.

Returns:

The number of flow charts that were resumed.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

sendToAuditTrail

void sendToAuditTrail(java.lang.String eventName,
                      java.lang.String eventMessage)
                      throws EngineException,
                             java.rmi.RemoteException

Publishes an audit trail event using the given name and message. Using this method, applications can provide updates on their status to the audit trail.

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.

For example, to report to the audit trail that an FTP server is unavailable, this method can be called with an event name like "FTP Server Status" and an event message like "ftp.company.com : down".

Parameters:

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

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

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

See Also:

AuditTrailTrigger

size

long size()
          throws EngineException,
                 java.rmi.RemoteException

Returns the number of flow charts in the engine.

Returns:

The number of flow charts in the engine.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

size

long size(java.lang.String namespace)
          throws EngineException,
                 java.rmi.RemoteException

Returns the number of flow charts in the specified hierarchical flow chart namespace within the engine.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Returns:

long The number of flow charts as specified by the hierarchical flow chart namespace expression. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.

sizeByState

long sizeByState(java.lang.String namespace,
                 SuperState superState,
                 SubState subState)
                 throws EngineException,
                        java.rmi.RemoteException

Returns the number of flow charts in the specified state and hierarchical flow chart namespace within the engine.

Parameters:

namespace - A number of flow charts in the hierarchical flow chart namespace. The namespace may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.

superState - The super-state of flow charts to count.

subState - The sub-state of flow charts to count.

Returns:

The number of FlowCharts in the given state.

Throws:

EngineException - If a system error occurs.

java.rmi.RemoteException - If a networking error occurs.