The Carbon Core Config Subsystem

Values within configuration documents can be references to values within other configuration documents or to Deployment Properties (see the BootStrap documentation). In this fashion, the value of an attribute in a document can be replaced by the value of an attribute in another document or by the value of a DeploymentProperty.

The notation for references to other configuration documents is:

<Attribute>{configuration-document-name$attrubute-name}</Attribute>

where configuration-document-name is the absolute name of the referenced configuration document and attrubute-name is the name of the referenced attribute within configuration-document-name. Attributes can be at any depth within the referenced document. To reference nested attributes, delimit the attribute names with '.' (e.g. {/foo/bar$a.b.c}).

The notation for references to Deployment Properties is:

<Attribute>{deployment-property-name}</Attribute>

where deployment-property-name is the name of a property found within the BootStrapper Deployment Properties.

Note that this is only supported for simple types of configuration attributes. To reference complex types, use the reference notation described above. Also note that references can be made from indexed or Map types, but indexed or Map types cannot be targets of references.

When a configuration document changes, an event is generated and all listening objects are notified. For an object to be a listener, it must implement the org.sape.carbon.core.config.node.event.NodeEventListener interface. In order for an object to receive notifications of configuration changes, it must register itself with the configuration service: Config.getInstance().addNodeListener("/name", this). Once the listener is added, its nodeChanged method will be called when the configuration has changed and the nodeRemoved method will be called if the node is removed.

The Configuration Service maintains a cache of Configuration objects in order to improve the speed Configuration object lookups. In addition, each Configuration object maintains an internal cache of properties to improve the performance of lookups. These are read optimizations that make write operations more expensive. This is OK because the vast majority of configuration usage is read-only.

Config.fetchConfiguration returns a Configuration object from the cache. This object read-only and therefore thread-safe and can be accessed via multiple threads. To access a writable copy of a configuration, call Config.fetchWritableConfiguration. This returns a writable configuration. This object is not thread-safe and cannot be shared across threads. It can only be accessed in a single threaded or synchronized context. A writable configuration can be switched to read-only mode by calling Configuration.setConfigurationReadOnly. This method must be called in a single threaded or synchronized context, but after it completes, the Configuration object is thread-safe and can be shared. Setting a Configuration to read-only cannot be undone. To get a writable version again, either create a clone of the read-only version which will be writable, or fetch the configuration anew from the Configuration Service. To modify the shared configuration cache, get a writable version of the Configuration you wish to modify, change it, then store it using Config.storeConfiguration. This will clear the cache causing subsequent fetches to reload Configurations.

There are two kinds of links that can exist with the configuration hierarchy: links within the existing hierarchy and links to external points. The former are similar to Unix file system links while the latter are similar to mounts of other file systems.

All links are created by configurations that are contained within link documents (e.g. on a file system, link documents are denoted by a .link extension). Link documents contain configurations that extend org.sape.carbon.core.config.node.link.LinkNodeConfiguration. This configuration interface specifies a single property, LinkNodeFactoryClass, which is the class object of an implementation of LinkNodeFactory. This factory is then used to construct the link node itself. Further configuration is specified by extensions to the LinkNodeConfiguration interface (see below). Links within the existing hierarchy are created by org.sape.carbon.core.config.node.link.GenericLinkNodeConfiguration. Beyond the factory class, this configuration specifies the target node of the link. This can be an absolute or relative path to the node. Note that GenericLinkNode cannot be used for the configuration root link.

Example GenericLinkNodeConfiguration

<Configuration
    ConfigurationInterface="org.sape.carbon.core.config.node.link.GenericLinkNodeConfiguration">

    <LinkNodeFactoryClass>org.sape.carbon.core.config.node.link.GenericLinkNodeFactory</LinkNodeFactoryClass>
    <TargetNodeName>/example</TargetNodeName>
</Configuration>

With the 2.0 release of Carbon, there 4 types of links that link to external points: