- Index

< Previous |  | Next >

# StreamBase Configuration in Depth

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.

Configuration model

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 TIBCO StreamBase using configuration files. The detailed syntax of these configuration files is described in the StreamBase Administration Guide. 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 `distribution`, it has a `name` of `myconfiguration`, and it is `version` `1.0`.

    //
    //     This file defines version 1.0 of a distribution configuration named myconfiguration
    //
    configuration "myconfiguration" version "1.0" type "distribution"
    {
         ...
    };

## Configuration Life Cycle

All configurations can go through the life cycle shown in Figure 2, “Configuration life cycle”.

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 successfully loads.

- Inactive — configuration data is loaded into a node, but it is not the active version.

- Active — the configuration version is active.

- Removed — configuration data was removed from the node. This is a transient state.

StreamBase allows only one active version 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.

### Replacing a version

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 TIBCO StreamBase transaction. For example, loading and activating version 2.0 to replace version 1.0 takes place as follows:

1. Configuration `type` `distribution` and `name` `myconfiguration` version 1.0 is active.

2. Configuration `type` `distribution` and `name` `myconfiguration` version 2.0 is loaded, passes audit, and is activated.

3. Configuration `type` `distribution` and `name` `myconfiguration` version 1.0 is now inactive, and configuration `type` `distribution` and `name` `myconfiguration` version 2.0 is active.

Because the configuration replacement is done in a single TIBCO StreamBase transaction, there is no disruption to a running application.

### Deactivating a Version

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.

## Configuration Notifiers

Applications can install configuration notifiers to respond to configuration events that are raised as the configuration transitions through its life cycle. See the StreamBase Java Developer's 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 must 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 | 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 is removable.