Apache » Cocoon »

  Cocoon Core

Cocoon Core 2.2

Property Configuration

Cocoon comes with a smart configuration mechanism based on property files. The configuration of Cocoon (or more precisely of the components) is based on XML files for the various components. To customize these configuration files without changing the files itself you can define properties to which you can refer to from within the configuration files (and sitemaps and your own code). In addition, Cocoon provides integrated support for the Spring property override mechanism.

Cocoon uses the Cocoon Spring Configurator for these features. You can find a complete description here. In short, you can define various property files and have different ways of configuring these properties. You can refer to the values of a property by using the common ${PROPERTY_NAME} syntax in your configuration files or sitemaps. You can also access these values in your Java code.

In addition the Spring Configurator supports different running modes, so you can define on startup which set of properties is used. This allows you to define different properties for production, development and test, for example.

Properties and Sitemaps


As explained above, you can simply refer to a value of a property within a sitemap. In addition a sitemap can have a set of own properties which are only available to this sitemap (and the components defined in this sitemap) and all sub sitemaps. This mechanism is a replacement for the deprecated global variables.

By default each sitemap tries to read properties from within the directory the sitemap is in, looking into these two directories: config/properties and config/properties/${RUNNING_MODE}. If you don't want to use these default locations, you can specify the attribute "use-default-include" with a value of "false" at the map:components element in the sitemap.

You can specify your own property directory where all property files are read from by using the element map:include-properties with the attribute dir specifying the directory location inside the map:components element in the sitemap.

If you don't want that Cocoon tries to replace strings containing a property reference in your sitemap, you can set the attribute replace-properties with the value false at the map:components element in the sitemap.

Please note, that you can't use properties to define the values for the attributes on the map:components element. This means that the possible values for "use-default-include" and "replace-properties" are hard-coded values which can't be changed using properties.

Properties and Java Code

If you need access to the defined properties within your Java code, just lookup the Settings bean. This bean provides access to all available properties. See the documentation about the Configuration API for more information.