flux.runtimeconfiguration
Interface RuntimeConfigurationNode

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable, VariableManager

public interface RuntimeConfigurationNode
extends VariableManager, java.lang.Cloneable

Used to populate the hierarchical flow chart namespace with configuration properties. Pre-defined properties can be used or custom properties can be added. These configuration properties can alter the behavior of executing flow charts. Note that names of nodes and configuration properties are case-insensitive.

Author:

Copyright 2014 Flux Corporation. All rights reserved.

Field Summary

static java.lang.String	CONCURRENCY_THROTTLE This property controls the number of flow charts in the current branch in the tree of flow charts that are allowed to execute concurrently.
static java.lang.String	CONCURRENCY_THROTTLE_CLUSTER_WIDE This property controls the number of flow charts in the current branch in the tree of flow charts that are allowed to execute concurrently.
static java.lang.String	DEFAULT_FLOW_CHART_ERROR_HANDLER This property specifies the default flow chart actions that are executed when a flow chart action raises an error and there is no explicit outbound error flow defined.
static java.lang.String	FIFO_SCHEDULING_ENABLED This property controls whether flows charts in the current branch in the tree of flow charts are scheduled for execution in a first-in-first-out manner.
static java.lang.String	INTERNAL_LOGGER_DEBUG_ENABLED This property controls whether action and trigger properties and variables are logged to the audit trail.
static java.lang.String	LISTENER_CLASSPATH This property specifies the listener classpath for flow charts, which is used to load listener classes in Java Actions and Dynamic Java Actions.
static java.lang.String	PRIORITY This property specifies the priority of flow charts in the current branch in the tree of flow charts.
static java.lang.String	RUN_AS_USER This property specifies the username under whose security context a flow chart executes.

Method Summary

void	clearChildren() Removes all the child nodes of this node.
java.lang.Object	clone() Returns a deep copy of this RuntimeConfiguration object.
boolean	containsProperty(java.lang.String propertyName) Indicates whether the specified property exists in this runtime configuration.
RuntimeConfigurationNode	getChild(java.lang.String unqualifiedName) Returns the child with the specified unqualified name.
java.util.SortedSet<RuntimeConfigurationNode>	getChildren() Returns all the child nodes of this node.
ConcurrencyThrottle	getConcurrencyThrottle() Returns the concurrency constraint for this node, if any.
ConcurrencyThrottle	getConcurrencyThrottleClusterWide() Returns the concurrency constraint for this node, if any, which applies to flow charts running across the entire cluster.
FlowChart	getDefaultFlowChartErrorHandler() Returns the default error handler for flow charts at or below the level of this node in the hierarchical flow chart namespace.
java.lang.String	getFullyQualifiedName() Returns the fully qualified name of this branch.
java.lang.String	getListenerClasspath() Returns the listener classpath for this node, if any.
RuntimeConfigurationNode	getParent() Returns the parent node of this node.
java.lang.Integer	getPriority() Returns the priority, if any, for flow charts at or below the level of this node in the hierarchical flow chart namespace.
java.lang.Object	getProperty(java.lang.String propertyName) Returns the runtime configuration property for the specified name.
java.lang.String	getRunAsUser() Returns the run-as-user property for this node, if any.
java.lang.String	getUnqualifiedName() Returns the base name of this branch.
boolean	isFifoSchedulingEnabled() Indicates whether first-in-first-out scheduling is enabled for this node in the hierarchical flow chart namespace.
boolean	isInternalLoggerDebugEnabled() Indicates whether action and trigger properties and variables are logged to the audit trail for this node in the hierarchical flow chart namespace.
RuntimeConfigurationNode	makeChild(java.lang.String unqualifiedName) Makes a new child for this node.
boolean	removeChild(java.lang.String unqualifiedName) Deletes the specified child of the current node.
boolean	removeProperty(java.lang.String propertyName) Deletes the specified runtime configuration property.
void	setConcurrencyThrottle(ConcurrencyThrottle concurrencyThrottle) Sets the concurrency throttle for this node.
void	setConcurrencyThrottle(int limit) Sets the concurrency throttle for this node.
void	setConcurrencyThrottle(java.lang.String concurrencyConstraint) Sets the concurrency throttle for this node.
void	setConcurrencyThrottleClusterWide(ConcurrencyThrottle concurrencyThrottle) Sets the concurrency throttle for this node, which applies to flow charts running across the entire cluster..
void	setConcurrencyThrottleClusterWide(int limit) Sets the concurrency throttle for this node, which applies to flow charts running across the entire cluster.
void	setConcurrencyThrottleClusterWide(java.lang.String concurrencyConstraint) Sets the concurrency throttle for this node, which applies to flow charts running across the entire cluster.
void	setDefaultFlowChartErrorHandler(FlowChart defaultErrorHandler) Sets the default error handler for flow charts at or below the level of this node in the hierarchical flow chart namespace.
void	setFifoSchedulingEnabled(boolean enabled) Sets whether first-in-first-out scheduling is enabled for this node in the hierarchical flow chart namespace.
void	setInternalLoggerDebugEnabled(boolean enabled) Sets the INTERNAL_LOGGER_DEBUG_ENABLED property for this node.
void	setListenerClasspath(java.lang.String listenerClasspath) Sets the listener classpath for this node.
void	setPriority(java.lang.Integer priority) Sets the priority, if any, for flow charts at or below the level of this node in the hierarchical flow chart namespace.
void	setProperty(java.lang.String propertyName, java.lang.Object property) Sets the runtime configuration property for the specified name.
void	setRunAsUser(java.lang.String runAsUser) Sets the run-as-user property for this node, if any.

Methods inherited from interface flux.VariableManager

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

Field Detail

CONCURRENCY_THROTTLE

static final java.lang.String CONCURRENCY_THROTTLE

This property controls the number of flow charts in the current branch in the tree of flow charts that are allowed to execute concurrently. This property applies to the local Flux engine only. The expression syntax for concurrency throttles is discussed in detail in the Flux Manual.

All concurrency throttle expressions from the current branch in the tree up to the root of the tree are taken into account when evaluating system-wide concurrency throttles at runtime.

If this property is not set at the root of the runtime configuration tree, it defaults to "10".

See Also:

Constant Field Values

CONCURRENCY_THROTTLE_CLUSTER_WIDE

static final java.lang.String CONCURRENCY_THROTTLE_CLUSTER_WIDE

This property controls the number of flow charts in the current branch in the tree of flow charts that are allowed to execute concurrently. This property applies to all Flux engines across the entire cluster. The expression syntax for concurrency throttles is discussed in detail in the Flux Software Developers Manual.

All cluster-wide concurrency throttle expressions from the current branch in the runtime configuration tree up to the root of the tree are taken into account when evaluating system-wide concurrency throttles at runtime.

See Also:

Constant Field Values

DEFAULT_FLOW_CHART_ERROR_HANDLER

static final java.lang.String DEFAULT_FLOW_CHART_ERROR_HANDLER

This property specifies the default flow chart actions that are executed when a flow chart action raises an error and there is no explicit outbound error flow defined. These default flow chart actions constitute the default flow chart error handler. When the default flow chart error handler finishes executing, control flows back to the main flow chart and resumes execution from the beginning of the last transaction.

The first default flow chart error handler found, when searching from the current branch in the runtime configuration tree up to the root of the tree, is used as the default flow chart error handler. If no default error handler is found, no default error handler is used.

See Also:

Constant Field Values

FIFO_SCHEDULING_ENABLED

static final java.lang.String FIFO_SCHEDULING_ENABLED

This property controls whether flows charts in the current branch in the tree of flow charts are scheduled for execution in a first-in-first-out manner. When enabled to do so, engines schedule flow charts for execution as follows. First, when a flow chart is originally submitted to an engine, the current timestamp is recorded. Next, when an engine is ready to execute a flow chart, an eligible-to-run flow chart with the oldest original-submission timestamp is selected first and scheduled for immediate execution.

Eligible-to-run flow charts include those flow charts that are not paused and have an eligible execution time that is older than the wall clock (the current time).

Next, if the concurrency throttle permits it, the next flow chart with the next-oldest original-submission timestamp is selected and scheduled for immediate execution.

Note that the first flow chart may not have finished executing or reached a trigger before the second flow chart begins executing. However, it is guaranteed that the first flow chart is scheduled to begin executing before the second flow chart is scheduled to begin executing.

If true queue-like behavior is desired -- where a second flow chart does not run until the first one finishes or reaches a trigger -- simply enable this property and set the concurrency throttle in the current branch to one.

Finally, flow chart priorities take precedence over FIFO scheduling. Priorities are considered first before FIFO scheduling is applied. In other words, higher priority flow charts still run before lower priority flow charts, even if the lower priority flow charts have older original-submission timestamps.

By default, first-in-first-out scheduling is disabled.

See Also:

Constant Field Values

INTERNAL_LOGGER_DEBUG_ENABLED

static final java.lang.String INTERNAL_LOGGER_DEBUG_ENABLED

This property controls whether action and trigger properties and variables are logged to the audit trail. When enabled, all action and trigger properties and variables in a flow chart are recorded to the audit trail when an action begins execution. By default, this property is disabled.

An internal logger must be configured in order to use this property.

See Also:

Constant Field Values

LISTENER_CLASSPATH

static final java.lang.String LISTENER_CLASSPATH

This property specifies the listener classpath for flow charts, which is used to load listener classes in Java Actions and Dynamic Java Actions.

If this property is not set at the root of the runtime configuration tree, it defaults to the directory "listeners".

The listener classpath is a list of directories and jar files. Each item in the list is separated by a ":" or ";" character. Each item contains a path to a directory or jar file containing "/" and "\" characters. On Windows, a letter followed by a ":" or ";" character is interpreted as a drive letter. If a directory is specified, any jar files under that directory are automatically included in alphabetical order in the classpath as well.

Alternately, the listener classpath is an HTTP URL that refers to a single jar file accessible over the network.

See Also:

FlowChart.setListenerClasspath(java.lang.String), Constant Field Values

PRIORITY

static final java.lang.String PRIORITY

This property specifies the priority of flow charts in the current branch in the tree of flow charts. Generally, higher priority flow charts run before lower priority flow charts. However, concurrency throttles always take precedence over flow chart priorities and can prevent high priority flow charts from running. Furthermore, a high priority flow chart can be blocked from running when it is waiting to consume a message from a message queue.

The highest priority is 1. Numbers that are greater than 1 constitute lower priorities. Negative numbers and 0 are not legal priorities. If no priority can be found, a flow chart's priority defaults to 10.

If the engine configuration permits it, flow chart priorities can temporarily rise over time in order to prevent lower priority flow charts from starving and never being allowed to execute due to the fact that higher priority flow charts generally run before lower priority flow charts. Once a flow chart with its temporarily elevated priority runs, its priority drops back to its original value. After this time, this flow chart's priority may temporarily rise again if it does not run frequently enough. The FAIRNESS_TIME_WINDOW engine configuration property governs whether a flow chart's priority is elevated if it begins to starve.

For additional information, see the FAIRNESS_TIME_WINDOW engine configuration property.

See Also:

Configuration.FAIRNESS_TIME_WINDOW, Constant Field Values

RUN_AS_USER

static final java.lang.String RUN_AS_USER

This property specifies the username under whose security context a flow chart executes. Applicable only for secure Flux engines. If set to a username, flow charts run as the specified user.

If this property is not set at the root of the runtime configuration tree, it defaults to the user who submitted a flow chart to the Flux engine. However, if a user with administrator privileges submitted a flow chart and specified a run-as user directly on the flow chart, then that flow chart runs as the user specified by the administrator.

This property has no effect unless the SECURITY_ENABLED configuration option is enabled.

See Also:

Configuration.SECURITY_ENABLED, Constant Field Values

Method Detail

clone

java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Returns a deep copy of this RuntimeConfiguration object.

Returns:

A deep copy of this RuntimeConfiguration object.

Throws:

java.lang.CloneNotSupportedException - If an error occurs.

clearChildren

void clearChildren()

Removes all the child nodes of this node.

containsProperty

boolean containsProperty(java.lang.String propertyName)

Indicates whether the specified property exists in this runtime configuration.

Parameters:

propertyName - The name of the property to check.

Returns:

Whether the specified property exists in this runtime configuration.

getChild

RuntimeConfigurationNode getChild(java.lang.String unqualifiedName)

Returns the child with the specified unqualified name. An unqualified name contains no "/" symbols.

Parameters:

unqualifiedName - The unqualified name of the child to return.

Returns:

The child with the specified unqualified name.

Throws:

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

getChildren

java.util.SortedSet<RuntimeConfigurationNode> getChildren()

Returns all the child nodes of this node. The nodes are sorted by name. Child nodes can be removed from this node through the SortedSet result.

Returns:

All the direct child nodes of this node. The result is not null, but it may be empty.

getConcurrencyThrottle

ConcurrencyThrottle getConcurrencyThrottle()

Returns the concurrency constraint for this node, if any.

Returns:

The concurrency constraint for this node, if any.

getConcurrencyThrottleClusterWide

ConcurrencyThrottle getConcurrencyThrottleClusterWide()

Returns the concurrency constraint for this node, if any, which applies to flow charts running across the entire cluster.

Returns:

The concurrency constraint for this node, if any, which applies to flow charts running across the entire cluster.

getDefaultFlowChartErrorHandler

FlowChart getDefaultFlowChartErrorHandler()

Returns the default error handler for flow charts at or below the level of this node in the hierarchical flow chart namespace. Default error handlers defined at lower levels in the hierarchical flow chart namespace may override this error handler.

Returns:

The default error handler for flow charts at or below the level of this node in the hierarchical flow chart namespace. Default error handlers defined at lower levels in the hierarchical flow chart namespace may override this error handler.

getFullyQualifiedName

java.lang.String getFullyQualifiedName()

Returns the fully qualified name of this branch. The name contains "/" symbols, one per level in the hierarchical flow chart namespace.

For example, if flow charts are split up into "heavyweight" and "lightweight" sections of the hierarchical flow chart namespace, the fully qualified name of heavyweight flow chart H is "/heavyweights/H", and the fully qualified name of lightweight flow chart L is "/lightweights/L".

Returns:

The name of this branch, which does not contain any "/" symbols.

getListenerClasspath

java.lang.String getListenerClasspath()

Returns the listener classpath for this node, if any. Listener classpath settings defined at lower levels in the hierarchical flow chart namespace may override this listener classpath setting.

Returns:

The listener classpath for this node, if any.

getParent

RuntimeConfigurationNode getParent()

Returns the parent node of this node.

Returns:

The parent node of this node. Returns null if this node is the root of the tree.

getPriority

java.lang.Integer getPriority()

Returns the priority, if any, for flow charts at or below the level of this node in the hierarchical flow chart namespace. Priorities defined at lower levels in the tree of flow charts may override this priority.

Returns:

The priority, if any, for flow charts at or below the level of this node in the hierarchical flow chart namespace. Priorities defined at lower levels in the tree of flow charts may override this priority.

getProperty

java.lang.Object getProperty(java.lang.String propertyName)

Returns the runtime configuration property for the specified name.

Parameters:

propertyName - The name of the property to retrieve.

Returns:

The runtime configuration property for the specified name or null if the property does not exist.

Throws:

java.lang.IllegalArgumentException - If the property name is null or empty.

getRunAsUser

java.lang.String getRunAsUser()

Returns the run-as-user property for this node, if any. Run-as-user settings defined at lower levels in the hierarchical flow chart namespace may override this run-as-user setting.

Returns:

The run-as-user setting for this node, if any.

See Also:

RUN_AS_USER

getUnqualifiedName

java.lang.String getUnqualifiedName()

Returns the base name of this branch. The name does not contain any "/" symbols.

Returns:

The base name of this branch, which does not contain any "/" symbols.

isFifoSchedulingEnabled

boolean isFifoSchedulingEnabled()

Indicates whether first-in-first-out scheduling is enabled for this node in the hierarchical flow chart namespace.

Returns:

Whether first-in-first-out scheduling is enabled for this node in the hierarchical flow chart namespace.

See Also:

FIFO_SCHEDULING_ENABLED

isInternalLoggerDebugEnabled

boolean isInternalLoggerDebugEnabled()

Indicates whether action and trigger properties and variables are logged to the audit trail for this node in the hierarchical flow chart namespace.

Returns:

Whether action and trigger properties and variables are logged to the audit trail for this node in the hierarchical flow chart namespace.

See Also:

INTERNAL_LOGGER_DEBUG_ENABLED

makeChild

RuntimeConfigurationNode makeChild(java.lang.String unqualifiedName)

Makes a new child for this node. The name may not contain any "/" symbols.

Parameters:

unqualifiedName - The unqualified name of the new child, which may not contain any "/" symbols.

Throws:

java.lang.IllegalArgumentException - If the name is null, is empty, contains a "/" symbol, or is a duplicate of another child node name.

removeChild

boolean removeChild(java.lang.String unqualifiedName)

Deletes the specified child of the current node.

Parameters:

unqualifiedName - The name of the child to delete.

Returns:

Whether a child with the specified name was found and deleted.

Throws:

java.lang.IllegalArgumentException - If the name is null, empty, or contains a "/" symbol.

removeProperty

boolean removeProperty(java.lang.String propertyName)

Deletes the specified runtime configuration property. The following properties may not be removed from the root of the runtime configuration tree: CONCURRENCY_THROTTLE and PRIORITY. These properties are required at the root of the runtime configuration tree.

Parameters:

propertyName - The name of the property to delete.

Returns:

Whether a property with the specified name was found and deleted.

Throws:

java.lang.IllegalArgumentException - If the property name is null or empty or if an attempt is made to remove a property that is required at the root of the runtime configuration tree.

See Also:

CONCURRENCY_THROTTLE, PRIORITY

setConcurrencyThrottle

void setConcurrencyThrottle(java.lang.String concurrencyConstraint)

Sets the concurrency throttle for this node. The concurrencyConstraint argument is used to create a concurrency throttle containing the specified concurrency throttle expression.

For example, the concurrency throttle expression "/lightweight flow charts/ <= 15" indicates that no more than 15 flow charts can run at a time from the "/lightweight flow charts/" branch of the flow chart tree.

Parameters:

concurrencyConstraint - The concurrency throttle for this node.

Throws:

java.lang.IllegalArgumentException - If concurrencyConstraint is null, empty, or does not represent a valid concurrency throttle expression.

setConcurrencyThrottle

void setConcurrencyThrottle(int limit)

Sets the concurrency throttle for this node. The limit argument is used to create a concurrency constraint containing the specified limit.

For example, a limit of 15 indicates that no more than 15 flow charts can run at a time from the current branch of the flow chart tree.

Parameters:

limit - The concurrency throttle for this node.

Throws:

java.lang.IllegalArgumentException - If limit is less than 0.

setConcurrencyThrottle

void setConcurrencyThrottle(ConcurrencyThrottle concurrencyThrottle)

Sets the concurrency throttle for this node. The concurrencyThrottle argument may be null, which indicates that there is no concurrency throttle for this node.

Parameters:

concurrencyThrottle - The concurrency throttle for this node. May be null.

Throws:

java.lang.IllegalArgumentException - If concurrencyThrottle is null.

setConcurrencyThrottleClusterWide

void setConcurrencyThrottleClusterWide(java.lang.String concurrencyConstraint)

Sets the concurrency throttle for this node, which applies to flow charts running across the entire cluster. The concurrencyConstraint argument is used to create a concurrency throttle containing the specified concurrency throttle expression.

For example, the concurrency throttle expression "/lightweight flow charts/ <= 15" indicates that no more than 15 flow charts can run at a time from the "/lightweight flow charts/" branch of the flow chart tree.

Parameters:

concurrencyConstraint - The concurrency throttle for this node.

Throws:

java.lang.IllegalArgumentException - If concurrencyConstraint is null, empty, or does not represent a valid concurrency throttle expression.

setConcurrencyThrottleClusterWide

void setConcurrencyThrottleClusterWide(int limit)

Sets the concurrency throttle for this node, which applies to flow charts running across the entire cluster. The limit argument is used to create a concurrency constraint containing the specified limit.

For example, a limit of 15 indicates that no more than 15 flow charts can run at a time from the current branch of the flow chart tree.

Parameters:

limit - The concurrency throttle for this node.

Throws:

java.lang.IllegalArgumentException - If limit is less than 0.

setConcurrencyThrottleClusterWide

void setConcurrencyThrottleClusterWide(ConcurrencyThrottle concurrencyThrottle)

Sets the concurrency throttle for this node, which applies to flow charts running across the entire cluster.. The concurrencyThrottle argument may be null, which indicates that there is no cluster-wide concurrency throttle for this node.

Parameters:

concurrencyThrottle - The concurrency throttle for this node. May be null.

Throws:

java.lang.IllegalArgumentException - If concurrencyThrottle is null.

setDefaultFlowChartErrorHandler

void setDefaultFlowChartErrorHandler(FlowChart defaultErrorHandler)

Sets the default error handler for flow charts at or below the level of this node in the hierarchical flow chart namespace. Default error handlers defined at lower levels in the hierarchical flow chart namespace may override this error handler.

Parameters:

defaultErrorHandler - The default error handler for flow charts at or below the level of this node in the hierarchical flow chart namespace. Default error handlers defined at lower levels in the hierarchical flow chart namespace may override this error handler.

setFifoSchedulingEnabled

void setFifoSchedulingEnabled(boolean enabled)

Sets whether first-in-first-out scheduling is enabled for this node in the hierarchical flow chart namespace.

Parameters:

enabled - Whether first-in-first-out scheduling is enabled for this node in the hierarchical flow chart namespace.

See Also:

FIFO_SCHEDULING_ENABLED

setInternalLoggerDebugEnabled

void setInternalLoggerDebugEnabled(boolean enabled)

Sets the INTERNAL_LOGGER_DEBUG_ENABLED property for this node.

Parameters:

enabled - Whether debugging is enabled for this node.

setListenerClasspath

void setListenerClasspath(java.lang.String listenerClasspath)

Sets the listener classpath for this node. The listener classpath argument may be null, which indicates there is no classpath setting defined at this node. Listener classpath settings defined at lower levels in the hierarchical flow chart namespace may override this listener classpath setting.

Parameters:

listenerClasspath - The listener classpath for this node. May be null.

setPriority

void setPriority(java.lang.Integer priority)

Sets the priority, if any, for flow charts at or below the level of this node in the hierarchical flow chart namespace. Priorities defined at lower levels in the tree of flow charts may override this priority.

Parameters:

priority - The priority, if any, for flow charts at or below the level of this node in the hierarchical flow chart namespace. Priorities defined at lower levels in the tree of flow charts may override this priority.

setProperty

void setProperty(java.lang.String propertyName,
                 java.lang.Object property)

Sets the runtime configuration property for the specified name.

Parameters:

propertyName - The name of the property to set.

property - The runtime configuration property to set. This object must follow the rules for persistent variables.

Throws:

java.lang.IllegalArgumentException - If the property name is null or empty.

setRunAsUser

void setRunAsUser(java.lang.String runAsUser)

Sets the run-as-user property for this node, if any. Run-as-user settings defined at lower levels in the hierarchical flow chart namespace may override this run-as-user setting.

Parameters:

runAsUser - The run-as-user setting for this node, if any.

See Also:

RUN_AS_USER