The Carbon Classloader-based Config Module

This service is not used directly by client code. Once configured, it plugs into Carbon's configuration subsystem and is used behind the scenes. The purpose of this document is to describe the configuration.

This service has two distinct possible usages. I can be used to load configuration branches out of a local classpath, such as inside a jar or ear. It may also be used with URL prefixes that allow an application to leverage Java's URLClassloader capabilities and place configuration branches inside of HTTP servers.

In order to access configurations stored in the classpath, a link must be created in the configuration hierachy. The link configuration needs to be of type org.sape.carbon.services.config.classloader.ClassloaderLinkNodeConfiguration. Within a ClassloaderLinkNodeConfiguration. To place the entire configuration structure into the classpath use the CarbonConfigRoot.link document and instance of ClassloaderLinkNodeConfiguration.

Example of a Local Classpath Link Configuration

<Configuration
    ConfigurationInterface="org.sape.carbon.services.config.classloader.ClassloaderLinkNodeConfiguration">

    <LinkNodeFactoryClass>org.sape.carbon.services.config.classloader.ClassloaderLinkNodeFactory</LinkNodeFactoryClass>
    <PathPrefix>config/</PathPrefix>
</Configuration>
            

The above example stores the config inside of a local classpath. For example, inside of an EAR file, there may be a CarbonConfig.jar, which contains a "config" directory that holds configuration.

Example of a URL Classpath Link Configuration

<Configuration
    ConfigurationInterface="org.sape.carbon.services.config.classloader.ClassloaderLinkNodeConfiguration">

    <LinkNodeFactoryClass>org.sape.carbon.services.config.classloader.ClassloaderLinkNodeFactory</LinkNodeFactoryClass>
    <PathPrefix>application-config/</PathPrefix>
    <ClassloaderURLsArray>
        <ClassloaderURLs>http://localhost:8080/</ClassloaderURLs>
    </ClassloaderURLsArray>
</Configuration>
            

The above example stores the config inside an http server with documents residing under http://localhost:8080/application-config.

The module may be used to store configuration inside of a local classpath. This is most appropriate when deploying an application as a completely self-contained JAR, EAR or WAR file.

When deploying a self-contained Enterprise Archive (EAR) it is recommended that Carbon configuration be stored inside of config directory in its own JAR file inside the EAR. The Class-path: property in the various manifests inside the EAR should contain a reference to the configuration jar. At the root of the configuration JAR one should place a CarbonConfigRoot.link document using the ClassloaderLinkNodeConfiguration and giving the config directory as the PathPrefix property.

When deploying a self-contained Web Archive (WAR) one may follow the JAR option mentioned in the previous paragraph and place it into the WEB-INF/lib directory of the WAR. Alternate one may leave the configuration exanded in the WEB-INF/classes directory. Both options are valid.

Storing configuration inside a URL classpath is straight-forward. The primary use is to have a centralized configuration shared by all nodes of an application (such as a cluster of machines). The server should be behind the DMZ on the network preventing outside systems from viewing the config repository.