Property Handling

For using properties in your configuration files, Spring provides the property placeholder configurer which you have to configure in your application context. The Spring Configurator has already built-in support for replacing property values in configuration files, so there is no additional work required anymore. In addition the Configurator reads properties from various standard locations.

In general, the Configurator works with directories containing property files and supports two areas where these directories can be located: somewhere in the classpath or in some directory in your web application. While the first area is very convenient for distributing properties within libraries, the second area is very easy to edit by administrators or developers.

Let's start with the full list of actions taken by the Spring Configurator to read in properties. During this process, various property files are read. If there is more than one definiton for a property, the last definition wins!

1. The classpath is scanned for property files inside jar files located at /META-INF/cocoon/properties/*.properties. Usually these property files are default values for beans distributed with the jar the property files are contained in. All these property files are read in alphabetical order.
2. All property files located at /WEB-INF/classes/META-INF/cocoon/properties/*.properties are read in alphabetical order.
3. The classpath is scanned for property files inside jar files located at /META-INF/cocoon/properties/[RUNNING_MODE]/*.properties. Usually these property files are default values in the given running mode for beans distributed with the jar the property files are contained in. All these property files are read in alphabetical order.
4. All property files located at /WEB-INF/classes/META-INF/cocoon/properties/[RUNNING_MODE]/*.properties are read in alphabetical order.
5. All property files from /WEB-INF/cocoon/properties/*.properties are read in alphabetical order.
6. All property files from /WEB-INF/cocoon/properties/[RUNNING_MODE]/*.properties are read in alphabetical order.
7. If the home directory of the current user contains a .cocoon/settings.properties file, this is read next.
8. If the system property org.apache.cocoon.settings is specified and points to a property file, this is read. If the system property points to a directory all property files from this directory are read in alphabetical order and all property files from the sub directory named [RUNNING_MODE] are read in alphabetical order.
9. If the servlet context init parameter org.apache.cocoon.settings is specified and points to a property file, this is read. If the system property points to a directory all property files from this directory are read in alphabetical order and all property files from the sub directory named [RUNNING_MODE] are read in alphabetical order.
10. If a property provider (see below) is configured in the application context, it is queried for a set of properties.
11. Read additional configured properties from the settings configuration in the application context.
12. Apply additional configured properties from the settings configuration in the application context.
13. Apply system properties.

Although this list might look very scary, it is in fact a very simple but powerful approach:

• If you want to use properties within your configurations, make sure to supply a default value through a property file which is stored in the jar containing your components.
• If you want to provide default values for different running modes, add these configurations to your jar as well.
• If you want to override default configurations, put them either in your own jar file and make sure that the name of your property file comes after the default configuration file in alphabetical order, or put your property file in /WEB-INF/classes/META-INF/cocoon/properties.
• If you want to override a default configuration depending on a running mode, add a property file at the same location as before but put it in a sub directory with the name of the running mode.
• To override properties globally, e.g. through an administrator, put the properties at /WEB-INF/cocoon/properties or /WEB-INF/cocoon/[RUNNING_MODE]/properties.
• If you want to change a configuration value during development you can just set it as a system property. (You can also add a property file with the values or define your own running mode of course.)
• If you have special requirements for property handling, you can add a property provider bean which is a Spring managed bean conforming to the org.apache.cocoon.configuration.PropertyProvider interface. For example, if you want to store your configurations inside a database or configure them through a jndi context, you can provide these values through a custom implementation.