flux
Interface Engine


public interface Engine

The Flux engine that executes flow charts and contains a variety of job scheduling, automated workflow, managed file transfer, and workload automation functionality.

Author:
Copyright 2014 Flux Corporation. All rights reserved.

Method Summary
 long clear()
          Removes all flow charts, users, roles, logs, audit trail entries, and, in general, all data associated with the cluster.
 void clearAuditTrail()
          Removes all audit trail entries.
 void clearLogs()
          Removes all log entries from the database.
 void clearRunHistory()
          Removes all run history entries.
 void clearRunHistory(java.lang.String namespace)
          Removes all run history entries for the specified namespace.
 long clearSignal(java.lang.String namespace, java.lang.String signal)
          Clears the specified signal from all flow charts specified by a hierarchical flow chart namespace expression.
 long clearSignals(java.lang.String namespace)
          Clears all signals from all flow charts specified by a hierarchical flow chart namespace expression.
 void dispose()
          Stops the engine, disposes all engine resources, and finally shuts down the engine.
 long expedite(java.lang.String namespace)
          Forces the specified flow charts to be executed as soon as possible.
 java.util.List<java.lang.String> findBusinessIntervalUsages(java.lang.String businessIntervalNamespace)
          Finds flow charts in the engine that reference the specified business interval.
 ForecastIterator forecast(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound)
          Returns an ordered result of flow charts, based on the next scheduled firing time of each flow chart, given all flow charts in the specified flow chart namespace and within the specified time range.
 FlowChartIterator get()
          Returns all flow charts ordered by flow chart name.
 FlowChart get(java.lang.String flowChartName)
          Returns a flow chart whose name matches the specified flow chart name.
 ActionHistoryIterator getActionHistory(java.lang.String flowChartName, java.util.Date lowerBound, java.util.Date upperBound)
          Returns historical execution timestamps which occurred within the lower and upper date boundaries for all actions and triggers in a flow chart.
 ActionHistoryIterator getActionHistory(java.lang.String flowChartName, java.util.Date lowerBound, java.util.Date upperBound, java.lang.String actionType)
          Returns historical execution timestamps which occurred within the lower and upper date boundaries for an action or trigger type in a flow chart.
 ActionHistoryIterator getActionHistory(java.lang.String flowChartName, java.lang.String actionName)
          Returns historical timestamps for an action or trigger in a flow chart.
 ActionHistoryIterator getActionHistory(java.lang.String flowChartName, java.lang.String actionName, java.util.Date lowerBound, java.util.Date upperBound)
          Returns historical execution timestamps which occurred within the lower and upper date boundaries for an action or trigger in a flow chart.
 AgentAdministrator getAgentAdministrator()
          Returns the agent administrator for this engine instance, which is responsible for registering agents, unregistering agents, monitoring agents, and accepting responses from agents.
 java.lang.String getAuditTrailExpiration()
          Returns a time expression indicating how old individual audit trail entries in the Flux audit trail must be before they are automatically pruned.
 long getAverageRuntime(java.lang.String namespace)
          Returns the average length of execution time in milliseconds for all runs in the specified namespace.
 long getAverageRuntime(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the average length of execution time in milliseconds for all runs in the specified namespace which occurred within the lower and upper date boundaries.
 long getAverageRuntimeForAction(java.lang.String flowChartName, java.lang.String actionName)
          Returns the average length of execution time for an action or trigger in a specific flow chart.
 long getAverageRuntimeForAction(java.lang.String flowChartName, java.lang.String actionName, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the average length of execution time for an action or trigger in a specific flow chart for all execution times which occurred in the specified date boundaries.
 long getAverageWaitTimeForTrigger(java.lang.String flowChartName, java.lang.String triggerName)
          Returns the average length of time a trigger in a specific flow chart took to fire.
 long getAverageWaitTimeForTrigger(java.lang.String flowChartName, java.lang.String triggerName, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the average length of time a trigger in a specific flow chart took to fire during the specified date boundaries.
 FlowChartIterator getByState(java.lang.String namespace, SuperState superState, SubState subState)
          Returns all flow charts in the given state and namespace, ordered first by flow chart super-state, then by flow chart sub-state, then by namespace.
 int getConcurrencyLevel()
          Returns the concurrency throttle limit in the root node of the runtime configuration tree, assuming the root concurrency throttle expression is "/ <= N", where N is the limit.
 Configuration getConfiguration()
          Returns the configuration for this engine instance.
 float getCpuUsage()
          Returns the percentage of CPU usage for the system running the Flux engine.
 FlowChartElementIterator getFlowChartElements(java.lang.String namespace)
          Returns the fundamental components of all flow charts, ordered by flow chart name, whose names match the specified hierarchical flow chart namespace expression.
 FlowChartElementIterator getFlowChartElements(java.lang.String namespace, SortOrder sortOrder)
          Returns the fundamental components of all flow charts, ordered by flow chart name, whose names match the specified hierarchical flow chart namespace expression.
 FlowChartElementIterator getFlowChartElements(java.lang.String namespace, SuperState superState, java.util.Set<SubState> subStates, java.lang.String engineName, java.lang.String actionName, java.lang.String messageFilter)
          Returns the fundamental components of all running flow contexts within executing flow charts that match the specified search criteria, which are described in the method parameters.
 FlowChartElementIterator getFlowChartElements(java.lang.String namespace, SuperState superState, java.util.Set<SubState> subStates, java.lang.String engineName, java.lang.String actionName, java.lang.String messageFilter, SortOrder sortOrder)
          Returns the fundamental components of all running flow contexts within executing flow charts that match the specified search criteria, which are described in the method parameters.
 FlowChartIterator getFlowCharts(java.lang.String namespace)
          Returns all flow charts, ordered by flow chart name, whose names match the specified hierarchical flow chart namespace expression.
 long getFreePhysicalMemory()
          Returns the amount of physical memory on the system running the engine, in kilobytes.
 long getFreeVirtualMemory()
          Returns the amount of free virtual memory on the system running the engine, in kilobytes.
 java.lang.String getLogExpiration()
          Returns a time expression indicating how old individual log entries in the Flux logs must be before they are automatically pruned.
 long getLongestRuntime(java.lang.String namespace)
          Returns the runtime in milliseconds of the longest flow chart run in the specified namespace.
 long getLongestRuntime(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the runtime in milliseconds of the longest flow chart run in the specified namespace which occurred within the lower and upper date boundaries.
 long getLongestRuntimeForAction(java.lang.String flowChartName, java.lang.String actionName)
          Returns the longest runtime in milliseconds for an action or trigger in a specific flow chart.
 long getLongestRuntimeForAction(java.lang.String flowChartName, java.lang.String actionName, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the longest runtime in milliseconds for an action or trigger in a specific flow chart for all execution times which occurred in the specified date boundaries.
 long getOpenRunCount(java.lang.String namespace)
          Returns the total number of flow chart runs that have not completed in the specified namespace which occurred within the lower and upper date boundaries.
 long getOpenRunCount(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the total number of flow chart runs which have not completed in the specified namespace which occurred within the lower and upper date boundaries.
 RepositoryAdministrator getRepositoryAdministrator()
          Returns the repository administrator which can be used to retrieve or manage flow charts in the flow chart repository.
 long getRunCount(java.lang.String namespace)
          Returns the total number of flow chart runs in the specified namespace.
 long getRunCount(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the total number of flow chart runs in the specified namespace that occurred within the lower and upper date boundaries.
 FlowChartRunIterator getRuns(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound)
          Returns all runs in the specified namespace that occurred within the lower and upper date boundaries.
 FlowChartRunIterator getRuns(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, SortOrder sortOrder)
          Returns all runs in the specified namespace that occurred within the lower and upper date boundaries.
 RuntimeConfigurationNode getRuntimeConfiguration()
          Returns the existing runtime configuration for this engine instance.
 SecurityAdministrator getSecurityAdministrator()
          Returns the security administrator for this Flux engine, which is responsible for managing users, roles, and other security issues.
 long getTotalPhysicalMemory()
          Returns the total amount of virtual memory on the system running the engine, in kilobytes.
 long getTotalVirtualMemory()
          Returns the total amount of virtual memory for the system running the engine, in kilobytes.
 long getUnsuccessfulRunCount(java.lang.String namespace)
          Returns the total number of unsuccessful flow chart runs in the specified namespace.
 long getUnsuccessfulRunCount(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound)
          Returns the total number of unsuccessful flow chart runs in the specified namespace which occurred within the lower and upper date boundaries.
 java.lang.String getVersion()
          Returns version information for this Flux engine.
 long interrupt(java.lang.String namespace)
          Interrupts the specified flow charts as soon as possible.
 boolean isDisposed()
          Indicates whether the engine has been disposed and is no longer usable.
 boolean isLoggedIn()
          For security purposes, indicates whether the current thread is logged into the engine as the specified user.
 boolean isRunning()
          Indicates if the engine has been started.
 boolean isSecured()
          Indicates whether a Flux engine has security enabled on it.
 boolean join(java.lang.String namespace, java.lang.String timeoutTimeExpression)
          Waits (blocks) until there are no flow charts in the specified namespace or a timeout occurs.
 boolean join(java.lang.String namespace, java.lang.String timeoutTimeExpression, java.lang.String pollingDelayTimeExpression)
          Waits (blocks) until there are no flow charts in the specified namespace or a timeout occurs.
 void login(java.lang.String username, java.lang.String password)
          For security purposes, logs the caller into the engine as the specified user.
 void logout()
          For security purposes, logs the caller out of the engine as the specified user.
 long pause(java.lang.String namespace)
          Pauses all flow charts specified by a hierarchical flow chart namespace expression.
 void ping()
          An empty method that performs absolutely no function except to verify that the engine is alive.
 java.lang.String put(FlowChart flowChart)
          Adds a new flow chart for execution, or if the flow chart already exists, modifies it.
 java.lang.String put(FlowChart flowChart, boolean replace)
          Adds a new flow chart for execution, or if the flow chart already exists on the engine, replaces it with a new one, if replace is set to true.
 long raiseSignal(java.lang.String namespace, java.lang.String signal)
          Raises the specified signal on all flow charts specified by a hierarchical flow chart namespace expression.
 long recover(java.lang.String namespace)
          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.
 long recover(java.lang.String namespace, boolean skipOffendingAction)
          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.
 long remove(java.lang.String namespace)
          Removes executing flow charts from the engine.
 long rename(java.lang.String oldNamespace, java.lang.String newNamespace)
          Renames all flow charts in the old namespace to the new namespace.
 void restart(Configuration configuration)
          Provides a way to reconfigure an engine without creating a new engine object.
 long restart(java.lang.String namespace)
          Restarts all flow charts specified by a hierarchical flow chart namespace expression.
 long resume(java.lang.String namespace)
          Resumes all flow charts specified by the hierarchical flow chart namespace expression.
 AuditTrailIterator scanAuditTrail(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, java.util.Set<java.lang.String> auditTrailEventNames, java.lang.String messageFilter)
          Returns an ordered result of audit trail entries from the Flux audit trail.
 AuditTrailIterator scanAuditTrail(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, java.util.Set<java.lang.String> auditTrailEventNames, java.lang.String messageFilter, SortOrder sortOrder)
          Returns an ordered result of audit trail entries from the Flux audit trail.
 AuditTrailIterator scanAuditTrailByUser(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, java.util.Set<java.lang.String> auditTrailEventNames, java.lang.String messageFilter, java.lang.String username)
          Returns an ordered result of audit trail entries from the Flux audit trail.
 AuditTrailIterator scanAuditTrailByUser(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, java.util.Set<java.lang.String> auditTrailEventNames, java.lang.String messageFilter, java.lang.String username, SortOrder sortOrder)
          Returns an ordered result of audit trail entries from the Flux audit trail.
 LogIterator scanLogs(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, Level loggingLevel, java.lang.String logger, java.lang.String messageFilter, java.lang.String engineName)
          Returns an ordered result of log entries from the Flux logs.
 LogIterator scanLogs(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, Level loggingLevel, java.lang.String logger, java.lang.String messageFilter, java.lang.String engineName, SortOrder sortOrder)
          Returns an ordered result of log entries from the Flux logs.
 LogIterator scanLogsByUser(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, Level loggingLevel, java.lang.String logger, java.lang.String messageFilter, java.lang.String engineName, java.lang.String username)
          Returns an ordered result of log entries from the Flux logs.
 LogIterator scanLogsByUser(java.lang.String namespace, java.util.Date lowerBound, java.util.Date upperBound, Level loggingLevel, java.lang.String logger, java.lang.String messageFilter, java.lang.String engineName, java.lang.String username, SortOrder sortOrder)
          Returns an ordered result of log entries from the Flux logs.
 void sendToAuditTrail(java.lang.String eventName, java.lang.String eventMessage)
          Publishes an audit trail event using the given name and message.
 void setAuditTrailExpiration(java.lang.String auditTrailExpiration)
          Sets a time expression indicating how old individual audit trail entries in the Flux audit trail must be before they are automatically pruned.
 void setConcurrencyLevel(int level)
          Sets the concurrency throttle limit in the root node of the runtime configuration tree, assuming the root concurrency throttle expression is "/ <= N", where N is the limit or level.
 void setLogExpiration(java.lang.String logExpiration)
          Sets a time expression indicating how old individual log entries in the Flux logs must be before they are automatically pruned.
 void setRuntimeConfiguration(RuntimeConfigurationNode runtimeConfiguration)
          Sets the runtime configuration for this engine instance to a new runtime configuration after this engine has been instantiated.
 long size()
          Returns the number of flow charts in the engine.
 long size(java.lang.String namespace)
          Returns the number of flow charts in the specified hierarchical flow chart namespace within the engine.
 long sizeByState(java.lang.String namespace, SuperState superState, SubState subState)
          Returns the number of flow charts in the specified state and hierarchical flow chart namespace within the engine.
 void start()
          Instructs the engine to start executing flow charts.
 void stop()
          Instructs the engine to stop executing flow charts.
 

Method Detail

clear

long clear()
           throws EngineException
Removes all flow charts, users, roles, logs, audit trail entries, and, in general, all data associated with the cluster. Furthermore, this method retains and resets the default administrator user account to its default settings. It also retains the default Administrator and Flow Chart Master security roles, which cannot be altered.

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.
EngineCommunicationException - If a networking error occurs.

clearAuditTrail

void clearAuditTrail()
                     throws EngineException
Removes all audit trail entries.

Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

clearLogs

void clearLogs()
               throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

clearRunHistory

void clearRunHistory()
                     throws EngineException
Removes all run history entries.

Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

clearRunHistory

void clearRunHistory(java.lang.String namespace)
                     throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

clearSignal

long clearSignal(java.lang.String namespace,
                 java.lang.String signal)
                 throws EngineException
Clears the specified signal 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.
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.
EngineCommunicationException - If a networking error occurs.

clearSignals

long clearSignals(java.lang.String namespace)
                  throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

dispose

void dispose()
             throws EngineException
Stops the engine, disposes all engine resources, and finally shuts down the engine. The engine waits for any running jobs to reach a stopping point before returning. After dispose() is called, all other methods will throw exceptions if called.

Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

expedite

long expedite(java.lang.String namespace)
              throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

findBusinessIntervalUsages

java.util.List<java.lang.String> findBusinessIntervalUsages(java.lang.String businessIntervalNamespace)
                                                            throws EngineException
Finds flow charts in the engine that reference the specified business interval.

Parameters:
businessIntervalNamespace - Namespace to a business interval located in the repository.
Returns:
Names of flow charts in the engine, sorted alphabetically, that reference the specified business interval.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

forecast

ForecastIterator forecast(java.lang.String namespace,
                          java.util.Date lowerBound,
                          java.util.Date upperBound)
                          throws EngineException
Returns an ordered result of flow charts, based on the next scheduled firing time of each flow chart, given all flow charts in the specified flow chart namespace and within the specified time range.

Only those flow charts that contain a timer trigger with a scheduled trigger date within the specified time range are included in the result. Note that if a timer trigger's scheduled trigger date has not been set, that timer trigger is not included in the forecast.

Returns a ForecastElement for each timer trigger in each flow chart that has a non-null scheduled trigger date. Note that if a flow chart contains more than one timer trigger with a scheduled trigger date set, there will be more than one entry in the iterator for that flow chart.

Note that the actual firing of flow charts may not directly correspond with the forecast due to a variety of factors.

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.
lowerBound - The left edge, inclusive, of the time range that includes expected firing times.
upperBound - The right edge, exclusive, of the time range that includes expected firing times.
Returns:
An ordered result of flow charts.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

get

FlowChartIterator get()
                      throws EngineException
Returns all flow charts ordered by flow chart name.

Directly modifying the returned flow charts has no effect. To modify a flow chart, call Engine.put().

Returns:
All flow charts ordered by flow chart name.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

get

FlowChart get(java.lang.String flowChartName)
              throws EngineException
Returns a flow chart whose name matches the specified flow chart name.

Directly modifying the returned FlowChart has no effect. To modify a flow chart, call Engine.put().

Parameters:
flowChartName - Specifies a flow chart in the hierarchical flow chart name space.
Returns:
A flow chart with the matching name or null if there is no such flow chart.
Throws:
java.lang.IllegalArgumentException - If flowChartName is null, empty, or contains a "*", "?", "%", "_", ".", or "$" character.
EngineException - If the flow chart name ends with a trailing slash, which refers to a branch in the hierarchical flow chart namespace; or a system error occurs.
EngineCommunicationException - If a networking error occurs.

getActionHistory

ActionHistoryIterator getActionHistory(java.lang.String flowChartName,
                                       java.lang.String actionName)
                                       throws EngineException
Returns historical timestamps for an action or trigger in a flow chart.

Parameters:
flowChartName - The absolute path to the flow chart containing the action or trigger. Wildcards are not permitted.
actionName - The name identifying an action or trigger in a flow chart.
Returns:
Historical execution timestamps for an action or trigger in a flow chart. Null if action history is not available for the specified action or trigger.
Throws:
java.lang.IllegalArgumentException - If the flow chart name or action name is null or empty or flow chart name contains a wildcard.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getActionHistory

ActionHistoryIterator getActionHistory(java.lang.String flowChartName,
                                       java.util.Date lowerBound,
                                       java.util.Date upperBound)
                                       throws EngineException
Returns historical execution timestamps which occurred within the lower and upper date boundaries for all actions and triggers in a flow chart.

Parameters:
flowChartName - The absolute path to a flow chart. Wildcards are not permitted.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
Returns:
Historical execution timestamps which occurred within the lower and upper date boundaries for all actions and triggers in a flow chart. Null is returned if action history is not available for the specified flow chart.
Throws:
java.lang.IllegalArgumentException - If the flow chart name is null or empty, the flow chart name contains a wildcard, the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getActionHistory

ActionHistoryIterator getActionHistory(java.lang.String flowChartName,
                                       java.lang.String actionName,
                                       java.util.Date lowerBound,
                                       java.util.Date upperBound)
                                       throws EngineException
Returns historical execution timestamps which occurred within the lower and upper date boundaries for an action or trigger in a flow chart.

Parameters:
flowChartName - The absolute path to the flow chart containing the action or trigger. Wildcards are not permitted.
actionName - The name identifying an action in a flow chart.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
Returns:
Historical execution timestamps which occurred within the lower and upper date boundaries for a specific flow chart. Null is returned if action history is not available for the specified flow chart.
Throws:
java.lang.IllegalArgumentException - If the flow chart name or action name is null or empty, the flow chart name contains a wildcard, the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getActionHistory

ActionHistoryIterator getActionHistory(java.lang.String flowChartName,
                                       java.util.Date lowerBound,
                                       java.util.Date upperBound,
                                       java.lang.String actionType)
                                       throws EngineException
Returns historical execution timestamps which occurred within the lower and upper date boundaries for an action or trigger type in a flow chart.

Parameters:
flowChartName - The absolute path to the flow chart containing the action or trigger. Wildcards are not permitted.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
actionType - The bean display name for the trigger or action in a flow chart. For example, the action type for a:
  • TimerTrigger is "Timer Trigger"
  • ConsoleAction is "Console Action"
Returns:
Historical execution timestamps which occurred within the lower and upper date boundaries for a specific flow chart. Null is returned if action history is not available for the specified flow chart.
Throws:
java.lang.IllegalArgumentException - If the flow chart name or action type is null or empty, the flow chart name contains a wildcard, the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getAgentAdministrator

AgentAdministrator getAgentAdministrator()
                                         throws EngineException
Returns the agent administrator for this engine instance, which is responsible for registering agents, unregistering agents, monitoring agents, and accepting responses from agents.

Returns:
The agent administrator for this engine instance.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getAuditTrailExpiration

java.lang.String getAuditTrailExpiration()
                                         throws EngineException
Returns a time expression indicating how old individual audit trail entries in the Flux audit trail must be before they are automatically pruned. Expired audit trail entries are automatically deleted from the database. A null audit trail expiration indicates that audit trail entries are never deleted from the database. By default, the audit trail expiration is "+w", one week.

The audit trail expiration is in effect only if the engine's logger is INTERNAL_ASYNCHRONOUS or INTERNAL_SYNCHRONOUS.

Returns:
A time expression indicating how old individual audit trail entries in the Flux audit trail must be before they are automatically pruned. A null audit trail expiration indicates that audit trail entries never expire.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
LoggerType.INTERNAL_ASYNCHRONOUS, LoggerType.INTERNAL_SYNCHRONOUS, Configuration.AUDIT_TRAIL_EXPIRATION

getAverageRuntime

long getAverageRuntime(java.lang.String namespace)
                       throws EngineException
Returns the average length of execution time in milliseconds for all runs in the specified namespace. A -1 is returned if no runs are found.

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 average runtime in milliseconds for all runs in the specified namespace or -1 if run averages are not found for the specified namespace.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getAverageRuntime

long getAverageRuntime(java.lang.String namespace,
                       java.util.Date lowerBound,
                       java.util.Date upperBound)
                       throws EngineException
Returns the average length of execution time in milliseconds for all runs in the specified namespace which occurred within the lower and upper date boundaries. A -1 is returned if no runs are found.

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.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
Returns:
The average runtime in milliseconds for all runs in the specified namespace which occured within the lower and upper date boundaries or -1 if run averages are not found for the specified namespace.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty or the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getAverageRuntimeForAction

long getAverageRuntimeForAction(java.lang.String flowChartName,
                                java.lang.String actionName)
                                throws EngineException
Returns the average length of execution time for an action or trigger in a specific flow chart. The runtime for a trigger is the length of time from when the trigger fires to when the trigger completes firing.

Parameters:
flowChartName - The absolute path to the flow chart containing the action or trigger. Wildcards are not permitted.
actionName - The name identifying an action or trigger in a specific flow chart.
Returns:
The average length of execution time for an action or trigger in a specific flow chart. -1 is returned if the average runtime is not available for the specified action or trigger.
Throws:
java.lang.IllegalArgumentException - If the namespace or action name is null or empty or namespace contains a wildcard.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getAverageRuntimeForAction

long getAverageRuntimeForAction(java.lang.String flowChartName,
                                java.lang.String actionName,
                                java.util.Date lowerBound,
                                java.util.Date upperBound)
                                throws EngineException
Returns the average length of execution time for an action or trigger in a specific flow chart for all execution times which occurred in the specified date boundaries.

Parameters:
flowChartName - The absolute path to the flow chart containing the action or trigger. Wildcards are not permitted.
actionName - The name identifying an action or trigger in a specific flow chart.
lowerBound - The left edge, inclusive, of the time range of runtime averages to be returned.
upperBound - The right edge, exclusive, of the time range of runtime averages to be returned.
Returns:
The average length of execution time for an action or trigger in a specific flow chart for all execution times which occurred in the specified date boundaries. -1 is returned if the average runtime is not available for this action or trigger during the specified date boundaries.
Throws:
java.lang.IllegalArgumentException - If the flow chart name or action name is null or empty, the flow chart name contains a wildcard, the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getAverageWaitTimeForTrigger

long getAverageWaitTimeForTrigger(java.lang.String flowChartName,
                                  java.lang.String triggerName)
                                  throws EngineException
Returns the average length of time a trigger in a specific flow chart took to fire.

Parameters:
flowChartName - The absolute path to the flow chart containing the trigger. Wildcards are not permitted.
triggerName - The name identifying a trigger in a specifc flow chart.
Returns:
The average length of time a trigger in a specific flow chart took to fire. -1 is returned if the average wait time is not available for the specified trigger. Zero is returned if the name to an action is supplied.
Throws:
java.lang.IllegalArgumentException - If the flow chart name or trigger name is null or empty or contain a wildcard.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getAverageWaitTimeForTrigger

long getAverageWaitTimeForTrigger(java.lang.String flowChartName,
                                  java.lang.String triggerName,
                                  java.util.Date lowerBound,
                                  java.util.Date upperBound)
                                  throws EngineException
Returns the average length of time a trigger in a specific flow chart took to fire during the specified date boundaries.

Parameters:
flowChartName - The absolute path to the flow chart containing the trigger. Wildcards are not permitted.
triggerName - The name identifying a trigger in a specific flow chart.
lowerBound - The left edge, inclusive, of the time range of wait averages to be returned.
upperBound - The right edge, exclusive, of the time range of wait averages to be returned.
Returns:
The average length of time a trigger in a specific flow chart took to fire during the specified date boundaries. -1 is returned if the average wait time is not available for this trigger during the specified date boundaries. Zero is returned if the name to an action is supplied.
Throws:
java.lang.IllegalArgumentException - If the flow chart name or trigger name is null or empty or the flow chart name contains a wildcard.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getByState

FlowChartIterator getByState(java.lang.String namespace,
                             SuperState superState,
                             SubState subState)
                             throws EngineException
Returns all flow charts in the given state and namespace, ordered first by flow chart super-state, then by flow chart sub-state, then by namespace.

Directly modifying the returned flow charts has no effect. To modify a flow chart, call Engine.put().

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 from which flow charts are selected.
subState - The sub-state from which flow charts are selected.
Returns:
All flow charts in the given namespace that are also in the given state.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getConcurrencyLevel

int getConcurrencyLevel()
                        throws EngineException
Returns the concurrency throttle limit in the root node of the runtime configuration tree, assuming the root concurrency throttle expression is "/ <= N", where N is the limit. Note that "N" is shorthand for "<path> <= N", where <path> is the current location in the runtime configuration tree.

This limit controls the number of flow charts that may be executing concurrently.

In essence, this method provides a shortcut to the concurrency throttle limit in the root node of the runtime configuration tree, for the sake of convenience.

Returns:
The concurrency throttle limit in the root node of the runtime configuration tree.
Throws:
EngineException - If the root concurrency throttle expression is not "/ <= N" or if a system error occurs.
EngineCommunicationException - If a networking error occurs.

getConfiguration

Configuration getConfiguration()
                               throws EngineException
Returns the configuration for this engine instance. Updating the returned configuration does not affect this engine instance's configuration.

Returns:
The configuration for this engine instance.
Throws:
EngineException - If security is enabled and insufficient security privileges have been granted to call this method.
EngineCommunicationException - If a networking error occurs.

getCpuUsage

float getCpuUsage()
                  throws EngineException
Returns the percentage of CPU usage for the system running the Flux engine. CPU usage is updated using the system resource command defined in the engine configuration.

Returns:
The percentage of CPU usage for the system running the Flux engine. This method returns -1 if the system resource command has not executed.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getFlowChartElements

FlowChartElementIterator getFlowChartElements(java.lang.String namespace)
                                              throws EngineException
Returns the fundamental components of all flow charts, ordered by flow chart name, whose names match the specified hierarchical flow chart namespace expression. If two results have the same namespace (that is, a flow chart has split into multiple execution flow contexts), then those results are returned in an arbitrary order.

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 fundamental components of all flow charts that match the namespace.
Throws:
java.lang.IllegalArgumentException - If namespace is null, empty, does not start with a "/" character, or includes the illegal namespace characters ".", "_", "%", or "$".
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getFlowChartElements

FlowChartElementIterator getFlowChartElements(java.lang.String namespace,
                                              SortOrder sortOrder)
                                              throws EngineException
Returns the fundamental components of all flow charts, ordered by flow chart name, whose names match the specified hierarchical flow chart namespace expression. If two results have the same namespace (that is, a flow chart has split into multiple execution flow contexts), then those results are returned in an arbitrary order.

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.
sortOrder - The sorting algorithm used to order the flow chart elements.
Returns:
The fundamental components of all flow charts that match the namespace.
Throws:
java.lang.IllegalArgumentException - If namespace is null, empty, does not start with a "/" character, or includes the illegal namespace characters ".", "_", "%", or "$".
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getFlowChartElements

FlowChartElementIterator getFlowChartElements(java.lang.String namespace,
                                              SuperState superState,
                                              java.util.Set<SubState> subStates,
                                              java.lang.String engineName,
                                              java.lang.String actionName,
                                              java.lang.String messageFilter)
                                              throws EngineException
Returns the fundamental components of all running flow contexts within executing flow charts that match the specified search criteria, which are described in the method parameters. Search criteria include namespace, super-state, sub-state, engine name, action name, and a message filter. Results are ordered by namespace. If two results have the same namespace (that is, a flow chart has split into multiple execution flow contexts), then those results are returned in an arbitrary order.

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 - All results contain a super-state that matches superState. If null, results can contain any super-state.
subStates - All results contain a sub-state that matches one of the specified sub-states. If null, results can contain any sub-state.
engineName - All results contain an engine that matches engineName. If null, results can contain any engine name.
actionName - All results contain an action that matches actionName. If null, results can contain any action name
messageFilter - All results include messages that contain the messageFilter in its entirety. If null, results can contain any message.
Returns:
The fundamental components of all running flow contexts within executing flow charts that match the specified search criteria.
Throws:
java.lang.IllegalArgumentException - If namespace is null, empty, does not start with a "/" character, or includes the illegal namespace characters ".", "_", "%", or "$".
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getFlowChartElements

FlowChartElementIterator getFlowChartElements(java.lang.String namespace,
                                              SuperState superState,
                                              java.util.Set<SubState> subStates,
                                              java.lang.String engineName,
                                              java.lang.String actionName,
                                              java.lang.String messageFilter,
                                              SortOrder sortOrder)
                                              throws EngineException
Returns the fundamental components of all running flow contexts within executing flow charts that match the specified search criteria, which are described in the method parameters. Search criteria include namespace, super-state, sub-state, engine name, action name, and a message filter. Results are ordered by namespace. If two results have the same namespace (that is, a flow chart has split into multiple execution flow contexts), then those results are returned in an arbitrary order.

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 - All results contain a super-state that matches superState. If null, results can contain any super-state.
subStates - All results contain a sub-state that matches one of the specified sub-states. If null, results can contain any sub-state.
engineName - All results contain an engine that matches engineName. If null, results can contain any engine name.
actionName - All results contain an action that matches actionName. If null, results can contain any action name
messageFilter - All results include messages that contain the messageFilter in its entirety. If null, results can contain any message.
sortOrder - The sorting algorithm used to order the flow chart elements.
Returns:
The fundamental components of all running flow contexts within executing flow charts that match the specified search criteria.
Throws:
java.lang.IllegalArgumentException - If namespace is null, empty, does not start with a "/" character, or includes the illegal namespace characters ".", "_", "%", or "$".
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getFlowCharts

FlowChartIterator getFlowCharts(java.lang.String namespace)
                                throws EngineException
Returns all flow charts, ordered by flow chart name, whose names match the specified hierarchical flow chart namespace expression.

Directly modifying a returned FlowChart has no effect. To modify a flow chart, call Engine.put().

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:
All flow charts that match the namespace.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getFreePhysicalMemory

long getFreePhysicalMemory()
                           throws EngineException
Returns the amount of physical memory on the system running the engine, in kilobytes.

Returns:
The amount of physical memory on the system running the engine, in kilobytes. A -1 is returned if the system resource command has not executed.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getFreeVirtualMemory

long getFreeVirtualMemory()
                          throws EngineException
Returns the amount of free virtual memory on the system running the engine, in kilobytes.

Returns:
The amount of free virtual memory on the system running the engine, in kilobytes. A -1 is returned if the system resource command has not executed.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getLogExpiration

java.lang.String getLogExpiration()
                                  throws EngineException
Returns a time expression indicating how old individual log entries in the Flux logs must be before they are automatically pruned. Expired log entries are automatically deleted from the database. A null log expiration indicates that log entries are never deleted from the database. By default, the log expiration is "+w", one week.

The log expiration is in effect only if the engine's logger is INTERNAL_ASYNCHRONOUS or INTERNAL_SYNCHRONOUS.

Returns:
A time expression indicating how old individual log entries in the Flux logs must be before they are automatically pruned. A null log expiration indicates that log entries never expire.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
LoggerType.INTERNAL_ASYNCHRONOUS, LoggerType.INTERNAL_SYNCHRONOUS, Configuration.LOG_EXPIRATION

getLongestRuntime

long getLongestRuntime(java.lang.String namespace)
                       throws EngineException
Returns the runtime in milliseconds of the longest flow chart run in the specified namespace. A -1 is returned if no runs are found.

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 runtime in milliseconds of the longest flow chart run in the specified namespace. A -1 is returned if no runs are found.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getLongestRuntime

long getLongestRuntime(java.lang.String namespace,
                       java.util.Date lowerBound,
                       java.util.Date upperBound)
                       throws EngineException
Returns the runtime in milliseconds of the longest flow chart run in the specified namespace which occurred within the lower and upper date boundaries. A -1 is returned if no runs are found.

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.
lowerBound - The left edge, inclusive, of the time range of runs to be included in the search.
upperBound - The right edge, exclusive, of the time range of runs to be included in the search.
Returns:
The runtime in milliseconds of the longest flow chart run in the specified namespace which occurred within the lower and upper date boundaries. A -1 is returned if no runs are found.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty or the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getLongestRuntimeForAction

long getLongestRuntimeForAction(java.lang.String flowChartName,
                                java.lang.String actionName)
                                throws EngineException
Returns the longest runtime in milliseconds for an action or trigger in a specific flow chart.

Parameters:
flowChartName - The absolute path to the flow chart containing the action or trigger. Wildcards are not permitted.
actionName - The name identifying an action or trigger in a specific flow chart.
Returns:
The longest runtime in milliseconds for an action or trigger in a specific flow chart.
Throws:
java.lang.IllegalArgumentException - If the namespace or action name is null or empty or namespace contains a wildcard.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getLongestRuntimeForAction

long getLongestRuntimeForAction(java.lang.String flowChartName,
                                java.lang.String actionName,
                                java.util.Date lowerBound,
                                java.util.Date upperBound)
                                throws EngineException
Returns the longest runtime in milliseconds for an action or trigger in a specific flow chart for all execution times which occurred in the specified date boundaries.

Parameters:
flowChartName - The absolute path to the flow chart containing the action or trigger. Wildcards are not permitted.
actionName - The name identifying an action or trigger in a specific flow chart.
lowerBound - The left edge, inclusive, of the time range of runs to be included.
upperBound - The right edge, exclusive, of the time range of runs to be included.
Returns:
The longest runtime in milliseconds for an action or trigger in a specific flow chart for all execution times which occurred in the specified date boundaries.
Throws:
java.lang.IllegalArgumentException - If the flow chart name or action name is null or empty, the flow chart name contains a wildcard, the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getOpenRunCount

long getOpenRunCount(java.lang.String namespace)
                     throws EngineException
Returns the total number of flow chart runs that have not completed in the specified namespace which occurred within the lower and upper date boundaries.

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:
Total number of flow chart runs which have not completed in the specified namespace.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getOpenRunCount

long getOpenRunCount(java.lang.String namespace,
                     java.util.Date lowerBound,
                     java.util.Date upperBound)
                     throws EngineException
Returns the total number of flow chart runs which have not completed in the specified namespace which occurred within the lower and upper date boundaries.

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.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
Returns:
Total number of flow chart runs which have not completed in the specified namespace which occurred within the lower and upper date boundaries.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty or the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getRepositoryAdministrator

RepositoryAdministrator getRepositoryAdministrator()
                                                   throws EngineException
Returns the repository administrator which can be used to retrieve or manage flow charts in the flow chart repository.

Returns:
The repository administrator for this engine instance.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getRunCount

long getRunCount(java.lang.String namespace)
                 throws EngineException
Returns the total number of flow chart runs in the specified namespace.

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:
Total number of flow chart runs in the specified namespace.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getRunCount

long getRunCount(java.lang.String namespace,
                 java.util.Date lowerBound,
                 java.util.Date upperBound)
                 throws EngineException
Returns the total number of flow chart runs in the specified namespace that occurred within the lower and upper date boundaries.

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.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
Returns:
Total number of flow chart runs in the specified namespace which occurred within the lower and upper date boundaries.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty or the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getRuns

FlowChartRunIterator getRuns(java.lang.String namespace,
                             java.util.Date lowerBound,
                             java.util.Date upperBound)
                             throws EngineException
Returns all runs in the specified namespace that occurred within the lower and upper date boundaries.

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.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
Returns:
All runs in the specified namespace which occurred within the lower and upper date boundaries or null if no runs are found.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty, the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getRuns

FlowChartRunIterator getRuns(java.lang.String namespace,
                             java.util.Date lowerBound,
                             java.util.Date upperBound,
                             SortOrder sortOrder)
                             throws EngineException
Returns all runs in the specified namespace that occurred within the lower and upper date boundaries.

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.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
sortOrder - The sorting algorithm used to order the runs.
Returns:
All runs in the specified namespace which occurred within the lower and upper date boundaries or null if no runs are found.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty, the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getRuntimeConfiguration

RuntimeConfigurationNode getRuntimeConfiguration()
                                                 throws EngineException
Returns the existing runtime configuration for this engine instance. Updating the returned runtime configuration does not affect this engine instance's runtime configuration.

This method is equivalent to Engine.getConfiguration().getRuntimeConfiguration().

Returns:
The existing runtime configuration for this engine instance.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
Configuration.RUNTIME_CONFIGURATION, getConfiguration(), Configuration.getRuntimeConfiguration()

getSecurityAdministrator

SecurityAdministrator getSecurityAdministrator()
                                               throws EngineException
Returns the security administrator for this Flux engine, which is responsible for managing users, roles, and other security issues.

Returns:
The security administrator for this Flux engine.
Throws:
EngineException - If security is enabled and insufficient security privileges have been granted to call this method.
EngineCommunicationException - If a networking error occurs.

getTotalPhysicalMemory

long getTotalPhysicalMemory()
                            throws EngineException
Returns the total amount of virtual memory on the system running the engine, in kilobytes.

Returns:
The total amount of virtual memory on the system running the engine, in kilobytes. A -1 is returned if the system resource command has not executed.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getTotalVirtualMemory

long getTotalVirtualMemory()
                           throws EngineException
Returns the total amount of virtual memory for the system running the engine, in kilobytes.

Returns:
The total amount of virtual memory for the system running the engine, in kilobytes. A -1 is returned if the system resource command has not executed.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getUnsuccessfulRunCount

long getUnsuccessfulRunCount(java.lang.String namespace)
                             throws EngineException
Returns the total number of unsuccessful flow chart runs in the specified namespace.

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:
Total number of unsuccessful flow chart runs in the specified namespace.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getUnsuccessfulRunCount

long getUnsuccessfulRunCount(java.lang.String namespace,
                             java.util.Date lowerBound,
                             java.util.Date upperBound)
                             throws EngineException
Returns the total number of unsuccessful flow chart runs in the specified namespace which occurred within the lower and upper date boundaries.

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.
lowerBound - The left edge, inclusive, of the time range of runs to be returned.
upperBound - The right edge, exclusive, of the time range of runs to be returned.
Returns:
Total number of unsuccessful flow chart runs in the specified namespace which occurred within the lower and upper date boundaries.
Throws:
java.lang.IllegalArgumentException - If the namespace is null or empty or the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

getVersion

java.lang.String getVersion()
                            throws EngineException
Returns version information for this Flux engine.

Returns:
Version information for this Flux engine.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

interrupt

long interrupt(java.lang.String namespace)
               throws EngineException
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).

Technically, 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.
EngineCommunicationException - If a networking error occurs.

isDisposed

boolean isDisposed()
                   throws EngineException
Indicates whether the engine has been disposed and is no longer usable.

Returns:
Whether the engine has been disposed.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

isLoggedIn

boolean isLoggedIn()
                   throws EngineCommunicationException
For security purposes, indicates whether the current thread is logged into the engine as the specified user.

Returns:
Whether the current thread is logged into the engine as the specified user.
Throws:
EngineCommunicationException - If a networking error occurs.

isRunning

boolean isRunning()
                  throws EngineException
Indicates if the engine has been started.

Returns:
Whether the engine has been started.
Throws:
EngineException - If security is enabled and insufficient security privileges have been granted to call this method.
EngineCommunicationException - If a networking error occurs.

isSecured

boolean isSecured()
                  throws EngineCommunicationException
Indicates whether a Flux engine has security enabled on it.

Returns:
Whether a Flux engine has security enabled on it.
Throws:
EngineCommunicationException - If a networking error occurs.

join

boolean join(java.lang.String namespace,
             java.lang.String timeoutTimeExpression)
             throws EngineException
Waits (blocks) until there are no flow charts in the specified namespace or a timeout occurs. The timeout time expression indicates the maximum amount of time that this method blocks while monitoring the specified namespace. The database is polled to check if there are no more flow charts. The frequency at which the database is polled is equal to the SYSTEM_DELAY engine configuration property. Longer polling delays provide better database performance.

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.
timeoutTimeExpression - The maximum amount of time that this method blocks while monitoring the specified namespace. The timeout time expression must be longer than the SYSTEM_DELAY engine configuration property.
Returns:
Whether a timeout occurred.
Throws:
EngineException - If namespace is null, timeoutTimeExpression is null, timeoutTimeExpression is not a positive time expression, timeoutTimeExpression is shorter than SYSTEM_DELAY, or a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
Configuration.SYSTEM_DELAY

join

boolean join(java.lang.String namespace,
             java.lang.String timeoutTimeExpression,
             java.lang.String pollingDelayTimeExpression)
             throws EngineException
Waits (blocks) until there are no flow charts in the specified namespace or a timeout occurs. The timeout time expression indicates the maximum amount of time that this method blocks while monitoring the specified namespace. The polling delay time expression indicates how often the database is polled to check if there are no more flow charts. Longer polling delays provide better database performance.

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.
timeoutTimeExpression - The maximum amount of time that this method blocks while monitoring the specified namespace. The timeout time expression must be longer than the polling delay time expression.
pollingDelayTimeExpression - The frequency at which this method checks the database to detect when there are no more flow charts. The polling delay time expression must be shorter than the timeout time expression.
Returns:
Whether a timeout occurred.
Throws:
EngineException - If namespace is null, timeoutTimeExpression is null, timeoutTimeExpression is not a positive time expression, pollingDelayTimeExpression is null, pollingDelayTimeExpression is not a positive time expression, timeoutTimeExpression is shorter than pollingDelayTimeExpression, or a system error occurs.
EngineCommunicationException - If a networking error occurs.

login

void login(java.lang.String username,
           java.lang.String password)
           throws EngineException
For security purposes, logs the caller into the engine as the specified user. After logging in, calls to the engine are performed in a security context.

Parameters:
username - The name of the user logging in.
password - The password of the user logging in.
Throws:
java.lang.IllegalArgumentException - If username is null or empty or if password is null or empty.
EngineException - If the username and password cannot be authenticated or if a system error occurs during the login process.
EngineCommunicationException - If a networking error occurs.

logout

void logout()
            throws EngineException
For security purposes, logs the caller out of the engine as the specified user. After logging out, calls to the engine are no longer performed in a security context.

Throws:
EngineException - If the specified username is not logged into the engine.
EngineCommunicationException - If a networking error occurs.

pause

long pause(java.lang.String namespace)
           throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

ping

void ping()
          throws EngineException
An empty method that performs absolutely no function except to verify that the engine is alive. This method is completely empty and does nothing. No security checks are performed. No log or audit trail is written.

Throws:
EngineException - If the engine is already disposed.
EngineCommunicationException - If a networking error occurs.

put

java.lang.String put(FlowChart flowChart)
                     throws EngineException
Adds a new flow chart for execution, or if the flow chart already exists, modifies it.

The name of the flow chart categorizes and organizes the flow chart in the flow chart namespace. If the flow chart name is null, empty, or refers to a directory in the flow chart namespace, then a fully qualified flow chart name is generated, using the supplied name as a prefix, when the flow chart is added.

For example, if no name is supplied, the engine generates a name and returns it from this method. One possible result is "/27".

As another example, suppose the supplied name is "/new york/data center/". Since this name ends in a slash ("/" symbol), the name refers to a directory. Consequently, a fully qualified name must be generated by the engine. In this example, the engine returns a fully qualified name of "/new york/data center/8293".

As a final example, suppose the supplied name is "/san francisco/my job". This flow chart name is already fully qualified. Therefore, the engine will not change it. The returned flow chart name is identical to the supplied name, "/san francisco/my job".

Note that when modifying a flow chart, only the properties or attributes of a flow chart's triggers, actions, and flows may be modified. If the structure of the flow chart is changed by adding or deleting triggers, actions, or flows, the modification will fail.

Furthermore, when modifying a flow chart, the flow chart must have been retrieved by one of the Engine.get() methods. If a new flow chart is used, an EngineException will be thrown.

Parameters:
flowChart - The flow chart to put into the engine.
Returns:
The fully qualified flow chart name.
Throws:
EngineException - If the structure of the flow chart would be changed, if a new flow chart is used to modify an existing one, or if a system error occurs.
EngineCommunicationException - If a networking error occurs.

put

java.lang.String put(FlowChart flowChart,
                     boolean replace)
                     throws EngineException
Adds a new flow chart for execution, or if the flow chart already exists on the engine, replaces it with a new one, if replace is set to true.

The name of the flow chart categorizes and organizes the flow chart in the flow chart namespace. If the flow chart name is null, empty, or refers to a directory in the flow chart namespace, then a fully qualified flow chart name is generated, using the supplied name as a prefix, when the flow chart is added.

For example, if no name is supplied, the engine generates a name and returns it from this method. One possible result is "/27".

As another example, suppose the supplied name is "/new york/data center/". Since this name ends in a slash ("/" symbol), the name refers to a directory. Consequently, a fully qualified name must be generated by the engine. In this example, the engine returns a fully qualified name of "/new york/data center/8293".

As a final example, suppose the supplied name is "/san francisco/my job". This flow chart name is already fully qualified. Therefore, the engine will not change it. The returned flow chart name is identical to the supplied name, "/san francisco/my job".

Note that when modifying a flow chart, only the properties or attributes of a flow chart's triggers, actions, and flows may be modified. If the structure of the flow chart is changed by adding or deleting triggers, actions, or flows, the modification will fail. You can override this behavior by setting replace flag to true, which removes existing workflow from the engine and replaces it with this one.

Furthermore, when modifying a flow chart, the flow chart must have been retrieved by one of the Engine.get() methods. If a new flow chart is used, an EngineException will be thrown.

Parameters:
flowChart - The flow chart to put into the engine.
replace - Overwrites flow chart on the engine if set to true.
Returns:
The fully qualified flow chart name.
Throws:
EngineException - If the structure of the flow chart would be changed, and replace is false, or if a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
put(FlowChart)

raiseSignal

long raiseSignal(java.lang.String namespace,
                 java.lang.String signal)
                 throws EngineException
Raises the specified signal on 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.
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.
EngineCommunicationException - If a networking error occurs.

recover

long recover(java.lang.String namespace)
             throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

recover

long recover(java.lang.String namespace,
             boolean skipOffendingAction)
             throws EngineException
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.
EngineCommunicationException - If a networking error occurs.
See Also:
Action.setSkippable(boolean)

remove

long remove(java.lang.String namespace)
            throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

rename

long rename(java.lang.String oldNamespace,
            java.lang.String newNamespace)
            throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

restart

void restart(Configuration configuration)
             throws EngineException
Provides a way to reconfigure an engine without creating a new engine object. Disposes this engine and reinstantiates it using the supplied configuration.

If this engine was created originally with Factory.makeEngine(String propertiesConfigurationFile), after a successful restart, the configuration file specified there will be overwritten with the new configuration supplied here. The purpose is that when the engine is restarted from a command line script, it will use the engine configuration data from the new configuration supplied here.

If an exception is thrown, this engine will become inactive until reset() is called successfully on it.

Parameters:
configuration - Properties that control how this engine behaves.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

restart

long restart(java.lang.String namespace)
             throws EngineException
Restarts all flow charts specified by a hierarchical flow chart namespace expression. Restarting a flow chart re-executes it from the very beginning without saving any data from its previous execution.

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 restarted.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

resume

long resume(java.lang.String namespace)
            throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

scanAuditTrail

AuditTrailIterator scanAuditTrail(java.lang.String namespace,
                                  java.util.Date lowerBound,
                                  java.util.Date upperBound,
                                  java.util.Set<java.lang.String> auditTrailEventNames,
                                  java.lang.String messageFilter)
                                  throws EngineException
Returns an ordered result of audit trail entries from the Flux audit trail.

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.

If namespace is null, audit trail entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of audit trail entries to be returned.
upperBound - The right edge, exclusive, of the time range of audit trail entries to be returned.
messageFilter - A filter that restricts the results to those audit trail entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
auditTrailEventNames - Filters out all audit trail events except for the specified events. If null or empty, all audit trail events are included.
Returns:
An ordered result of audit trail entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, or a system error occurs.
EngineCommunicationException - If a networking error occurs.

scanAuditTrail

AuditTrailIterator scanAuditTrail(java.lang.String namespace,
                                  java.util.Date lowerBound,
                                  java.util.Date upperBound,
                                  java.util.Set<java.lang.String> auditTrailEventNames,
                                  java.lang.String messageFilter,
                                  SortOrder sortOrder)
                                  throws EngineException
Returns an ordered result of audit trail entries from the Flux audit trail.

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.

If namespace is null, audit trail entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of audit trail entries to be returned.
upperBound - The right edge, exclusive, of the time range of audit trail entries to be returned.
auditTrailEventNames - Filters out all audit trail events except for the specified events. If null or empty, all audit trail events are included.
messageFilter - A filter that restricts the results to those audit trail entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
sortOrder - The sorting algorithm used to order the audit trail.
Returns:
An ordered result of audit trail entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, or a system error occurs.
EngineCommunicationException - If a networking error occurs.

scanAuditTrailByUser

AuditTrailIterator scanAuditTrailByUser(java.lang.String namespace,
                                        java.util.Date lowerBound,
                                        java.util.Date upperBound,
                                        java.util.Set<java.lang.String> auditTrailEventNames,
                                        java.lang.String messageFilter,
                                        java.lang.String username)
                                        throws EngineException
Returns an ordered result of audit trail entries from the Flux audit trail.

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.

If namespace is null, audit trail entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of audit trail entries to be returned.
upperBound - The right edge, exclusive, of the time range of audit trail entries to be returned.
auditTrailEventNames - Filters out all audit trail events except for the specified events. If null or empty, all audit trail events are included.
messageFilter - A filter that restricts the results to those audit trail entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
username - The name of the user responsible for generating this audit trail entry. If username is null, audit trail entries from any user are returned.
Returns:
An ordered result of audit trail entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, or a system error occurs.
EngineCommunicationException - If a networking error occurs.

scanAuditTrailByUser

AuditTrailIterator scanAuditTrailByUser(java.lang.String namespace,
                                        java.util.Date lowerBound,
                                        java.util.Date upperBound,
                                        java.util.Set<java.lang.String> auditTrailEventNames,
                                        java.lang.String messageFilter,
                                        java.lang.String username,
                                        SortOrder sortOrder)
                                        throws EngineException
Returns an ordered result of audit trail entries from the Flux audit trail.

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.

If namespace is null, audit trail entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of audit trail entries to be returned.
upperBound - The right edge, exclusive, of the time range of audit trail entries to be returned.
auditTrailEventNames - Filters out all audit trail events except for the specified events. If null or empty, all audit trail events are included.
messageFilter - A filter that restricts the results to those audit trail entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
username - The name of the user responsible for generating this audit trail entry. If username is null, audit trail entries from any user are returned.
sortOrder - The sorting algorithm used to order the audit trail.
Returns:
An ordered result of audit trail entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, or a system error occurs.
EngineCommunicationException - If a networking error occurs.

scanLogs

LogIterator scanLogs(java.lang.String namespace,
                     java.util.Date lowerBound,
                     java.util.Date upperBound,
                     Level loggingLevel,
                     java.lang.String logger,
                     java.lang.String messageFilter,
                     java.lang.String engineName)
                     throws EngineException
Returns an ordered result of log entries from the Flux logs.

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.

If namespace is null, log entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of log entries to be returned.
upperBound - The right edge, exclusive, of the time range of log entries to be returned.
loggingLevel - The granularity of log entries to return.
logger - One of the three engine loggers -- "client", "flow_chart", or "system" -- to which the returned log entries are restricted. If logger is null, log entries generated by any logger are returned.
messageFilter - A filter that restricts the results to those log entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
engineName - Each engine in a cluster is named. Restricts the returned log entries to those entries matching the specified engine. If engine name is null, log entries from any engine are returned.
Returns:
An ordered result of log entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, or a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
Configuration.CLIENT_LOGGER, Configuration.FLOW_CHART_LOGGER, Configuration.SYSTEM_LOGGER

scanLogs

LogIterator scanLogs(java.lang.String namespace,
                     java.util.Date lowerBound,
                     java.util.Date upperBound,
                     Level loggingLevel,
                     java.lang.String logger,
                     java.lang.String messageFilter,
                     java.lang.String engineName,
                     SortOrder sortOrder)
                     throws EngineException
Returns an ordered result of log entries from the Flux logs.

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.

If namespace is null, log entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of log entries to be returned.
upperBound - The right edge, exclusive, of the time range of log entries to be returned.
loggingLevel - The granularity of log entries to return.
logger - One of the three engine loggers -- "client", "flow_chart", or "system" -- to which the returned log entries are restricted. If logger is null, log entries generated by any logger are returned.
messageFilter - A filter that restricts the results to those log entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
engineName - Each engine in a cluster is named. Restricts the returned log entries to those entries matching the specified engine. If engine name is null, log entries from any engine are returned.
sortOrder - The sorting algorithm used to order the logs.
Returns:
An ordered result of log entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, or a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
Configuration.CLIENT_LOGGER, Configuration.FLOW_CHART_LOGGER, Configuration.SYSTEM_LOGGER

scanLogsByUser

LogIterator scanLogsByUser(java.lang.String namespace,
                           java.util.Date lowerBound,
                           java.util.Date upperBound,
                           Level loggingLevel,
                           java.lang.String logger,
                           java.lang.String messageFilter,
                           java.lang.String engineName,
                           java.lang.String username)
                           throws EngineException
Returns an ordered result of log entries from the Flux logs. The caller must have administrator privileges.

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.

If namespace is null, log entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of log entries to be returned.
upperBound - The right edge, exclusive, of the time range of log entries to be returned.
loggingLevel - The granularity of log entries to return.
logger - One of the three engine loggers — "client", "flow_chart", or "system" — to which the returned log entries are restricted. If logger is null, log entries generated by any logger are returned.
messageFilter - A filter that restricts the results to those log entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
engineName - Each engine in a cluster is named. Restricts the returned log entries to those entries matching the specified engine. If engine name is null, log entries from any engine are returned.
username - The name of the user responsible for generating this log entry. If username is null, log entries from any user are returned.
Returns:
An ordered result of log entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, the logging level is null, username is null, or a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
Configuration.CLIENT_LOGGER, Configuration.FLOW_CHART_LOGGER, Configuration.SYSTEM_LOGGER

scanLogsByUser

LogIterator scanLogsByUser(java.lang.String namespace,
                           java.util.Date lowerBound,
                           java.util.Date upperBound,
                           Level loggingLevel,
                           java.lang.String logger,
                           java.lang.String messageFilter,
                           java.lang.String engineName,
                           java.lang.String username,
                           SortOrder sortOrder)
                           throws EngineException
Returns an ordered result of log entries from the Flux logs. The caller must have administrator privileges.

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.

If namespace is null, log entries from any flow chart are returned.

lowerBound - The left edge, inclusive, of the time range of log entries to be returned.
upperBound - The right edge, exclusive, of the time range of log entries to be returned.
loggingLevel - The granularity of log entries to return.
logger - One of the three engine loggers — "client", "flow_chart", or "system" — to which the returned log entries are restricted. If logger is null, log entries generated by any logger are returned.
messageFilter - A filter that restricts the results to those log entries that match the specified message filter. The message filter may include the wildcard characters "*" and "?". The "*" character matches any character zero or more times, and the "?" character matches any character exactly once.
engineName - Each engine in a cluster is named. Restricts the returned log entries to those entries matching the specified engine. If engine name is null, log entries from any engine are returned.
username - The name of the user responsible for generating this log entry. If username is null, log entries from any user are returned.
sortOrder - The sorting algorithm used to order the logs.
Returns:
An ordered result of log entries.
Throws:
java.lang.IllegalArgumentException - If the lower bound is null, the upper bound is null, or the lower bound is greater than or equal to the upper bound.
EngineException - If the Flux engine's logger type is not LoggerType.ASYNCHRONOUS or LoggerType.SYNCHRONOUS, the logging level is null, username is null, or a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
Configuration.CLIENT_LOGGER, Configuration.FLOW_CHART_LOGGER, Configuration.SYSTEM_LOGGER

sendToAuditTrail

void sendToAuditTrail(java.lang.String eventName,
                      java.lang.String eventMessage)
                      throws EngineException
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.
EngineCommunicationException - If a networking error occurs.
See Also:
AuditTrailTrigger

setAuditTrailExpiration

void setAuditTrailExpiration(java.lang.String auditTrailExpiration)
                             throws EngineException
Sets a time expression indicating how old individual audit trail entries in the Flux audit trail must be before they are automatically pruned. Expired audit trail entries are automatically deleted from the database. A null audit trail expiration indicates that audit trail entries are never deleted from the database.

The audit trail expiration is in effect only if the engine's logger is INTERNAL_ASYNCHRONOUS or INTERNAL_SYNCHRONOUS.

Setting this audit trail expiration also updates this engine's AUDIT_TRAIL_EXPIRATION configuration property.

Parameters:
auditTrailExpiration - A time expression indicating how old individual audit trail entries in the Flux audit trail must be before they are automatically pruned. A null audit trail expiration indicates that audit trail entries never expire.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
LoggerType.INTERNAL_ASYNCHRONOUS, LoggerType.INTERNAL_SYNCHRONOUS, Configuration.AUDIT_TRAIL_EXPIRATION

setConcurrencyLevel

void setConcurrencyLevel(int level)
                         throws EngineException
Sets the concurrency throttle limit in the root node of the runtime configuration tree, assuming the root concurrency throttle expression is "/ <= N", where N is the limit or level.

This limit controls the number of flow charts that may be executing concurrently in the entire Flux engine.

In essence, this method provides a shortcut to the concurrency throttle limit in the root node of the runtime configuration tree, for the sake of convenience.

If the Flux engine is secured, the caller must have administrator privileges.

Parameters:
level - The concurrency throttle limit in the root node of the runtime configuration tree.
Throws:
EngineException - If the root concurrency throttle expression is not "/ <= N", the Flux engine is secured and the caller does not have administrator privileges, or a system error occurs.
EngineCommunicationException - If a networking error occurs.

setLogExpiration

void setLogExpiration(java.lang.String logExpiration)
                      throws EngineException
Sets a time expression indicating how old individual log entries in the Flux logs must be before they are automatically pruned. Expired log entries are automatically deleted from the database. A null log expiration indicates that log entries are never deleted from the database.

The log expiration is in effect only if the engine's logger is INTERNAL_ASYNCHRONOUS or INTERNAL_SYNCHRONOUS.

Setting this log expiration also updates this engine's LOG_EXPIRATION configuration property.

Parameters:
logExpiration - A time expression indicating how old individual log entries in the Flux logs must be before they are automatically pruned. A null log expiration indicates that log entries never expire.
Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
LoggerType.INTERNAL_ASYNCHRONOUS, LoggerType.INTERNAL_SYNCHRONOUS, Configuration.LOG_EXPIRATION

setRuntimeConfiguration

void setRuntimeConfiguration(RuntimeConfigurationNode runtimeConfiguration)
                             throws EngineException
Sets the runtime configuration for this engine instance to a new runtime configuration after this engine has been instantiated.

If the Flux engine is secured, the caller must have administrator privileges.

Parameters:
runtimeConfiguration - The new runtime configuration for this engine instance.
Throws:
java.lang.IllegalArgumentException - If runtimeConfiguration is null or invalid.
EngineException - The Flux engine is secured and the caller does not have administrator privileges or a system error occurs.
EngineCommunicationException - If a networking error occurs.
See Also:
Configuration.RUNTIME_CONFIGURATION

size

long size()
          throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

size

long size(java.lang.String namespace)
          throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

sizeByState

long sizeByState(java.lang.String namespace,
                 SuperState superState,
                 SubState subState)
                 throws EngineException
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.
EngineCommunicationException - If a networking error occurs.

start

void start()
           throws EngineException
Instructs the engine to start executing flow charts.

Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.

stop

void stop()
          throws EngineException
Instructs the engine to stop executing flow charts. This method blocks until all running flow charts have stopped. Once stopped, the engine can be restarted.

Throws:
EngineException - If a system error occurs.
EngineCommunicationException - If a networking error occurs.


© 2014 Flux Corporation. All rights reserved.