Contents
StreamBase® supports online versioning of configuration data. This allows a configuration to change without having to restart a running application. Configuration data is stored as managed objects in shared memory. Applications can define their own configuration data by defining a Java class. Application defined configuration data is operationally managed the same way as predefined StreamBase® configuration data.
Figure 1, “Configuration model” shows the configuration concepts.
These concepts are defined as:
-
Type — a specific category of configuration data that is loaded in a single configuration file. A configuration type consists of one or more configuration classes.
-
Class — a Java configuration class. This Java class defines a new configuration object. All configuration classes are associated with a configuration type.
-
Name — a unique name per configuration type. Multiple unique names can be associated with a configuration type. The configuration name is the unit of versioning.
-
Version — a unique configuration version per configuration name. Multiple versions can be associated with a configuration name, but only one can be active.
-
Objects — zero or more configuration objects associated with a configuration version. All of the configuration objects are associated with one of the configuration classes associated with the related configuration type.
-
Notifier — a configuration notifier that handles configuration state changes (see Configuration Notifiers).
Configuration data is loaded into StreamBase® using configuration files. The detailed syntax of these configuration files is described in the StreamBase® Administration. In addition to the configuration data for the configuration objects, the configuration files also contain:
-
Type — type of configuration data
-
Name — configuration name
-
Version — version number of configuration file
The type, name, and version information in the configuration files maps directly to the configuration concepts described above.
The type information in a configuration file is used to locate any configuration notifiers associated with the configuration data. The name and version are used to create or replace a configuration when the configuration is activated. See Configuration Life Cycle for more details.
For example, this configuration file is associated with a configuration type of com.tibco.ep.dtm.configuration.node, it has a name of my-node-configuration,
and it is version 1.0.0.
//
// This file defines version 1.0.0 of a node configuration named
// my-node-configuration
//
name = "my-node-configuration"
type = "com.tibco.ep.dtm.configuration.node"
version = "1.0.0"
configuration = { ... }
All configuration can go through the life cycle shown in Figure 2, “Configuration life cycle”.
The possible configuration states are:
-
Loaded — configuration data has been loaded into a StreamBase® node. This is a transient state. The configuration data automatically transitions to the Inactive state once it has been successfully loaded.
-
Inactive — configuration data is loaded into a node, but it is not the active version.
-
Removed — configuration data has been removed from the node. This is a transient state.
Only one active version is
allowed for each configuration name within a
type. For example, if there are two versions,
version 1.0 and version 2.0, of a configuration file with a name value of myconfiguration
and a type of distribution, only one can be active at a time in a node.
An audit step occurs before any configuration state changes to ensure that the configuration change does not cause runtime application failures. If an audit fails, the configuration state change does not occur and the application is left in the previous known good state.
All configuration state changes are only allowed when a node is in the Started state (see Figure 7, “Node life cycle”).
When one version of a configuration type and name is active, and a new version is activated, the old version is replaced. That is, the old version is deactivated and the new version is activated as a single StreamBase® transaction. For example, loading and activating version 2.0 to replace version 1.0 takes place as follows:
-
Configuration type
distributionand namemyconfigurationversion 1.0 is active. -
Configuration type
distributionand namemyconfigurationversion 2.0 is loaded, passes audit, and is activated. -
Configuration type
distributionand namemyconfigurationversion 1.0 is now inactive, and configuration typedistributionand namemyconfigurationversion 2.0 is active.
Because the configuration replacement is done in a single StreamBase® transaction, there is no disruption to a running application.
Deactivating a configuration version does not restore any previously active version. Another version must be activated, or loaded and activated, as a separate step. (Until this is done, there is no active version.) Nor does deactivating a version unload it; it must be explicitly removed to achieve this. Until removed, a deactivated version remains available to be reactivated again without having to reload the configuration data.
Applications may install configuration notifiers to respond to configuration events that are raised as the configuration transitions through its life cycle. See the StreamBase® Transactional Memory Developers Guide for details on how configuration notifiers are installed. Configuration notifiers are associated with a configuration type. Multiple notifiers can be installed for a configuration type. If multiple configuration notifiers are installed, the order in which they are called is undefined.
Configuration notifiers support:
-
auditing of configuration data and application state before a state change occurs
-
modifying application behavior based on a configuration state change
Audit notifier methods should ensure that the configuration state transition being audited can occur successfully. If the state transition cannot occur successfully, either because of invalid configuration data values or the current state of the application, the audit method reports a failure. If an audit fails, the configuration state change does not occur.
State transition audits
| State Transition | Description |
|---|---|
| load | Configuration load audit. This audit occurs after the configuration data is loaded into memory. |
| activate | Configuration activate audit. This audit method is called when there is no previous version of the configuration data with the specified type and name active. |
| replace | Configuration replace audit. This audit method is called when there is a previous version of the specified type and name active. |
| inactive | Configuration deactivation audit. |
| remove | Configuration remove audit. |
Following a successful audit (except for load), a notifier method is called to perform application specific behavior associated with the configuration state transition. The application state change methods cannot fail — all validation should have been done by the associated audit method.
State transition methods
| State Transition | Description |
|---|---|
| load | Configuration data successfully loaded. |
| active | Configuration activation succeeded. This method is called when there is no previous version of the configuration data with the specified type and name active. |
| replace | Replace existing configuration data. This method is called when there is a previous version of the specified type and name active. |
| inactive | Configuration data successfully deactivated. |
Notice that there is no method associated with removing configuration data. Configuration data removal is handled without any application involvement, other than auditing that the configuration data can be removed.