Package com.kabira.platform.switchconfig

Configuration Service

See: Description

Class Summary

Class	Description
Config	Base class for all configuration data.
ConfigurationListener	Listener for lifecycle changes to configuration versions.
Group	Representation of a named configuration.
GroupKind	Navigable representation of a configuration type.
Notifier	Deprecated Notifier has been replaced by ConfigurationListener.
Version	A single configuration version.

Enum Summary

Enum	Description
Version.State	State of version

Exception Summary

Exception	Description
ConfigurationException	Specialization of OperationFailed that uses the detail message and cause constructor parameters to set the value of the OperationFailed.reason field.
OperationFailed	Deprecated OperationFailed has been replaced by ConfigurationException.

Package com.kabira.platform.switchconfig Description

Configuration Service

The configuration framework provides a mechanism for loading and versioning groups of related application configuration data. Configuration data is collected into groups. It is the group that is versioned. Operations for loading, replacing, etc, are carried out on the group atomically.

A specific instance of a loaded group has a version, and can be uniquely identified by the key:

   (groupId, versionId)

Multiple versions of the same data group can exist in the system at a given time. However, only one is said to be "active". Applications interact only with the active group.

The ConfigurationListener class provides notifier methods that the application implements to be notified of configuration state changes. They are:

• loaded
• activated
• replaced
• deactivated
• removed

The loaded method is called when a version is loaded. The activated method is called when there is not already an active version. Replaced is called if there is a version already active that is being replaced with a new active version. Deactivated is called when a version is being deactivated without making another version active. And finally, removed is called when a version is removed.

ConfigurationListener also provides audit methods associated with each of the configuration state change methods defined above. The audit methods are called before the related configuration state change methods (except load). An audit method raises a ConfigurationException exception to indicate to the configuration service that the audit has failed, and that it should not continue with the configuration state change. In this case, the new version is not activated and the previous version (if any) stays active.

The audit methods provided by ConfigurationListener are:

• auditLoad
• auditActivate
• auditReplace
• auditDeactivate
• auditRemove

See the description of these methods for detailed information on when they are called.

To help partition the notifiers in a system, an identifier called type is introduced to specify the type of the configuration data. Applications create a ConfigurationListener instance for a particular configuration type (i.e. group kind), and the notifiers for that ConfigurationListener instance will be called only when configuration data matching that configuration type (i.e. group kind) has a state change.

• GroupKind: broad grouping or classification of configuration data
• GroupKind, GroupId: A group of configuration data within a broad classification
• GroupKind, GroupId, VersionId: A specific version of a data group within a broad classification

Configuration Loading

Configuration data is loaded by a loader.

A loader is responsible for setting the GroupKind, GroupId and VersionId of the objects being loaded.

A loader will fail the load operation if the node is currently throttling incoming work. The loader provides an ignoreThrottle option to specify if the load should proceed even though throttling is occurring.

A "maximum objects" limit can be set on the number of objects that can be contained within a configuration version. This limit is defined per configuration type. The load operation will fail if the configuration data being loaded exceeds the defined limit.

A "maximum versions" limit can be set on the number of versions that can exist for a group. This limit is defined per group. When defining a "maximum versions" limit you also specify what action the load operation should take when the "maximum versions" limit has been exceeded. The possible actions are fail the load operation or remove the group's oldest inactive version.

The configuration limits described above are set by loading and activating a kcs configuration of type "Configuration".

Configuration Containment

Sometimes a developer may wish to hide the use of dependent configuration from a user. This allows the developer to present a simplified configuration interface to the user while hiding the complexity of the implementation.

To use configuration containment, a developer would define a ConfigurationListener for its configuration type which implements the loaded() virtual method. The loaded method can create additional configuration objects programatically and return them to the configuration service. These additional configuration objects will be added to the version and managed atomically with the version's other configuration objects. The notifiers for each added object's configuration type will be called when the version is audited, activated, etc.

The notifiers for contained configuration objects' will be invoked before the containing group's notifiers. As an example, if the containing type is A, and A's loaded notifier adds configuration objects belonging to types B and C, and B's loaded notifier adds configuration objects belonging to types B1 and B2, the notifier calling order will be B1 B2 B C A.