The Carbon Java Framework  

The Carbon Core Config Subsystem

Advanced Configuration Service Usage

Author: Douglas Voet (dvoet at
Version: $Revision: 1.4 $($Author: jdreed $ / $Date: 2004/01/26 22:16:58 $)
Created: May 2003

Attribute Value References

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:


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:


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.

Configuration Events

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.

Caching and Threading

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 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 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



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

File System

The file system hierarchy implementation is included in the Carbon core. Links can be made to a directory or file that exists on the file system. Configuration documents end with a .xml extension. Link documents end with a .link extension. Links to a file system hierarchy are created by org.sape.carbon.core.config.node.file.FileLinkNodeConfigurations. This configuration interface adds LinkToPath to the properties defined in LinkNodeConfiguration. This path specifies the target file or directory of the link.

Example FileLinkNodeConfiguration




The jar hierarchy implementation is included in the config-jar module. While jars do not actually contain an analogy to folders, jar entries are named with their full path as they would exist on a file system. Links can be made to a jar entry or to any part of an entries name ending in '/'. Configuration documents end with a .xml extension. Link documents end with a .link extension. Links to a jar hierarchy are created by This configuration defines the location of the jar (TargetJarPath) and the target of the link within the jar (TargetRootWithinJar) (if this is omitted, the root of the jar is used).

Example JarLinkNodeConfiguration




Config-Classloader Service Usage

Classloader hierarchies work similarly to jar hierarchies in that classloaders do not contain an analogy to folders, but resources are named with a full path. Links can be made to a resource or to a path prefix. Classloader hierarchies are different than any other because changes made to configurations during the execution of an application do not last beyond the application's termination. The classloader resources are unaffected by any configuration changes.

Configuration documents end with a .xml extension. Link documents end with a .link extension. Links to a classloader hierarchy are created by This configuration adds PathPrefix to what is defined by LinkNodeConfiguration. Only resources that start with the value of PathPrefix loaded by the config service.

The Classloader Link Node Configuration can also contain URL classpath prefixes to allow storing Carbon configuration on HTTP or other servers capable of being accessed by URL.

Example ClassloaderLinkNodeConfiguration




Config-JNDI Service Usage

The JNDI hierarchy implementation is included in the config-jndi module. Links can be made to DirContexts on a directory server. Configuration documents' type attribute is 'doc'. Link documents' type attribute is 'link'. Links to a JNDI hierarchy are created by

Copyright © 2001-2003, Sapient Corporation