The Carbon Core Config Subsystem

Carbon / Reference / Core / Config

Locating Root Config

Author: Jordan Reed (jreed at sapient.com)
Version: $Revision: 1.2 $($Author: dvoet $ / $Date: 2003/09/26 19:18:25 $)
Created: August 2003

Introduction
Locating the Configuration Root

Method #1 - Deployment Property
Method #2 - Classloader
Method #3 - Default

Selecting the Appropriate Method for Your Project

Introduction

This document details the steps that Carbon's configuration service uses to locate the root of the configuration tree.

Locating the Configuration Root

The logic used to locate the root of the configuration tree in Carbon can be found in org.sape.carbon.core.bootstrap.BootConfigurationDocument. Carbon locates the root of the configuration system through a single link referred to as the RootLink. This link document is a Config Link of any of the types supported by Carbon (for a list of supplied link types for Carbon, see Carbon Configuration Links).

Method #1 - Deployment Property

Carbon's first step in locating the RootLink is to check for the existence of a deployment property called carbon.config.RootLink. This property would contain a valid file location of the file root link file. (e.g. c:/myproject/config/RootLink.link).

For information on specifying deployment properties, see the Deployment Properties Usage Guide.

Method #2 - Classloader

The second step used to locate the config root is through the classloader. Carbon will attempt to classload a resource named CarbonConfigRoot.link.

Method #3 - Default

Failing the first two methods, Carbon will use an internal default configuration document which looks like the following:

<Configuration ConfigurationInterface="org.sape.carbon.core.config.node.file.FileLinkNodeConfiguration"> <LinkNodeFactoryClass>org.sape.carbon.core.config.node.file.FileLinkNodeFactory</LinkNodeFactoryClass> <LinkToPath>{carbon.config.Path}</LinkToPath> </Configuration>

This document is just an instance of a FileLinkNodeConfiguration document with a single deployment property specified for the location of the root of the config service. This deployment property would typically be a file reference to a directory on the system containing the start of configuration (e.g. c:/myproject/config).

Carbon logs the method it used to locate the root config node at the INFO level and you should see a message similar to one of the following when Carbon loads:

Using file to load configuration root link: file name [c:/myproject/config/RootLink.link]
Using ClassLoader to load configuration root link: resource [file://c:/myproject/config/RootLink.link]
Configuration root link wasn't located, Using default config root link

Selecting the Appropriate Method for Your Project

Method #2 is generally the preferred method for allowing Carbon to locate the root of the configuration tree. It allows this information to be contained within your project's deployment (a JAR, EAR, etc.) and also allows the root link document to be switched to a different type (classloader, jndi, etc.) without significant change to the project.

Method #3 often serves as a fallback method when a project knows that its configuration will always be located on the filesystem. The project can still make use of the convenience of classloading the information by placing the deployment property for carbon.config.Path into the classloaded CarbonDeploymentConfig.properties file.

For more information about links see Advanced Usage - Links.