HOCON Configuration Merging

Prior to StreamBase 10.5.0, a given engine was allowed one engine configuration; StreamBase now supports merging configurations of certain properties within respective engine configurations (namely, the StreamBaseEngine, the LDMEngine, and the JavaEngine configuration root objects). Multiple configurations can now have affinity with an engine.

Upon configuration activation (which can occur during deploy and runtime), a root object's contents are merged with those of other root objects of the same class. Configuration merging should not be planned to occur during "design-time settings"; the process of activation configuration requires load configuration before activation can occur.

On configuration replacement, the new root object contents replace the previous one's and are re-merged. Merge semantics are specific to each root object. Note that the engine(s) that the configuration belongs to must be stopped before you can activate an updated configuration. The rest of the node can still be running.

These engine configurations contain settings that (1) can overlap between design time and deploy time, and (2) can apply to multiple fragments (top-level and dependent) that comprise the application running on an engine. Consider how you want your application to handle these settings when designing your application.

Essentially merging can occur at deploy time, where an administrator can decide to add additional configuration to the configuration, which is embedded in the fragment and application archive using the epadmin install node --nodedeploy command.

StreamBase defines a small number of cardinality behaviors, with respect to configuration. Some of these behaviors are singletons in nature (node, engine), others are named entities. To maintain consistency and minimize complexity, all root objects fall into one of the following singleton categories.

A given node can have exactly one instance of the root object. Any attempt to activate a configuration containing a second instance will fail. New versions of the configuration containing the node singleton root object are permitted, with the new root object replacing the existing one. Node singleton objects do not have merge semantics.

A given node can have any number of instances of the root object, but a given engine can have affinity with exactly one instance of the root object. Any attempt to activate a configuration containing a second instance having affinity with the same engine will fail. New versions of the configuration containing the engine singleton root object are permitted, with the new root object replacing the existing one.

Again, multiple versions of the same engine singleton are allowed — the most recent version "wins". Engine configurations support merging as explained above.

A given node can have any number of instances of the root object. The root object has a name that uniquely identifies it (or contains sub-objects that are uniquely named, typically in an associative array). Any attempt to activate a configuration containing another root object or sub-object with the same name will fail. New versions of the configuration containing the named entity are permitted, with the new root object replacing the existing one.

Named entities contain settings that are shared by other configuration objects. Imagine an authentication realm shared by multiple listeners, or a JDBC data source shared by multiple engines, or parameter settings shared by multiple EventFlow deployments.

Named entities do not have merge semantics. All you can do is replace a named entity with a newer version of the entity; you cannot take two named entities defined in different configurations and combine them.

A given node can have any number of instances of the root object. The root object is identified by class and owning configuration name+type+version (recall a configuration file of a given type can contain zero or one of each of the root objects of that type). Upon configuration activation, its contents are merged with those of other root objects of the same class. Upon configuration replacement, the new root object contents replace the previous one's and are re-merged. Merge semantics are specific to each root object.