cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Created: Running Modes
Date Thu, 11 Jan 2007 08:46:45 GMT
A new document has been created.

Document ID: 1309
Branch: main
Language: default
Name: Running Modes
Document Type: Cocoon Document
Created: 1/11/07 8:46:33 AM
Creator (owner): Carsten Ziegeler
State: publish


Mime type: text/xml
Size: 10710 bytes

<h1>The Cocoon Spring Configurator</h1>

<p>The Spring Configurator is a useful component providing support in common
configuration issues when using the Spring framework. Although this product has
been developed inside the Cocoon project, it is aimed at making easier the usage
of Spring in each and every web application; it is not tied to the famous Cocoon
web application framework and can be used standalone. The impact on your code is
nearly zero and the Spring Configurator as only Spring itself as a dependency.


<p>When using a framework like Spring there are always the same problems to
solve, like</p>

<li>Where do I store my bean configurations?</li>
<li>How can I parameterize them dynamically?</li>
<li>Where do I store these extra information?</li>
<li>How can I handle different environments like a testing environment, a
development environment and a production environment?</li>
<li>How can I distribute not only code but also corresponding configurations?
<li>How can I distribute partial web applications?</li>
<li>How do I manage hierarchial web application contexts?</li>

<p>Of course Spring is flexible enough to enable solutions to the above
problems, but you have to do it and implement it for your solution. And there is
more than one way of doing this and each and every project ends up developing
its own "proprietary" solution. A best practice and a standardized way of doing
these things would be great. And guess what, the Spring Configurator is the
answer to your problems. Like Maven has standardized the build process, the
Spring Configurator standardizes the way of dealing with various configuration
issues with Spring. Ok, enough motivation, let's see what the Spring
configurator can provide for your work.</p>


<p>The Spring Configurator requires</p>

<li>the Spring Framework Version 2.0.1 (or above)</li>
<li>JDK 1.4 (or above)</li>
<li>Servlet API 2.3 (or above)</li>

<p>The Spring Configuration requires two additional jar files, the Cocoon
Configuration API and the Cocoon Spring Configurator, which you can either
download here or from a public Maven repository by adding the Spring
Configurator as a dependency to your project:</p>

<p><strong>TODO - Show dependency configuration</strong></p>


<p>The Spring Configurator uses the Spring the
<a href="">extensible
XML authoring features</a> and therefore it can be directly used in your Spring
bean configurations. Usually you add the configurator to your global web
application context configuration (which is usually located at
<em>/WEB-INF/applicationContext.xml</em>). The extensible XML authoring requires
that you use the schema based configuration for Spring. Just add the required
namespace definition, a reference to the configurator XML schema to your bean

<pre>&lt;beans xmlns=""

<p>Then you can initialize the configurator by adding the <tt>settings</tt>
element to your bean configuration:</p>

<pre>   &lt;!-- Activate Cocoon Spring Configurator --&gt;

<p>And then...</p>

<h2>Running Modes</h2>

<p>The configurator provides the support of <em>running modes</em>. A running
mode defines the environment the application is currently running in. For
example this can be during development, a test setup or production. As you will
see in just some paragraphs, the configurator can use different configurations
and settings depending on the running mode.</p>

<p>A running mode is just a unique text key, like <tt>dev</tt>, <tt>test</tt>
or <tt>prod</tt>. This key is used to determine the correct configuration at
runtime. Although you can use any text key, it is advisable to use one of the
standard keys (dev, test or prod).</p>

<p>The running mode can be set in two ways: you can either set it in your
<tt>applicationContext.xml</tt> as a configuration for the <tt>settings

<pre>   &lt;!-- Activate Cocoon Spring Configurator --&gt;
   &lt;configurator:settings runningMode="test"/&gt;

<p>Or you can define the running mode by setting the system property
<tt>org.apache.cocoon.mode</tt> on startup of your web application, usually you
do this by specifying <tt>-Dorg.apache.cocoon.mode=test</tt> when starting your
application server. The system property has precedence over the value from the
application context. The default running mode is <tt>prod</tt>.</p>

<h2>Property Configurations</h2>

<p>For using properties in your configuration files, Spring provides the
<a href="">property
placeholder configurer</a> 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

<p>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.</p>

<p>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!</p>

<li>The classpath is scanned for property files inside jar files located at
<tt>/META-INF/cocoon/properties/*.properties.</tt> 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.</li>
<li>All property files located at
<tt>/WEB-INF/classes/META-INF/cocoon/properties/*.properties</tt> are read in
alphabetical order.</li>
<li>The classpath is scanned for property files inside jar files located at
<tt>/META-INF/cocoon/properties/[RUNNING_MODE]/*.properties.</tt> 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.</li>
<li>All property files located at
are read in alphabetical order.</li>
<li>All property files from <tt>/WEB-INF/cocoon/properties/*.properties</tt>
are read in alphabetical order.</li>
<li>All property files from
<tt>/WEB-INF/cocoon/properties/[RUNNING_MODE]/*.properties</tt> are read in
alphabetical order.</li>
<li>If the home directory of the current user contains a
<tt>.cocoon/</tt> file, this is read next.</li>
<li>If the system property <tt>org.apache.cocoon.settings</tt> is specified
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.</li>
<li>If a property provider (see below) is configured in the application context,
it is queried for a set of properties.</li>
<li>Read additional configured properties from the settings configuration in the
application context.</li>
<li>Apply additional configured properties from the settigns configuration in
the application context.</li>
<li>Apply system properties.</li>

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

<li>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.</li>
<li>If you want to provide default values for different running modes, add these
configurations to your jar as well.</li>
<li>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
<li>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.</li>
<li>To override properties globally, e.g. through an administrator, put the
properties at <tt>/WEB-INF/cocoon/properties</tt> or
<li>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.)</li>
<li>If you have special requirements for property handling, you can add a
property provider bean which is a Spring managed bean conforming to the
<tt>org.apache.cocoon.configuration.PropertyProvider</tt> 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

<h2>Configuring Log4j</h2>

<p>You can use the Configurator to
configure <a href="">Log4j</a> through an XML
configuration file:</p>

<pre>  &lt;bean name="org.apache.cocoon.spring.configurator.log4j"
    &lt;property name="resource" value="/WEB-INF/cocoon/log4j.xconf"/&gt;

<p>The property <tt>resource</tt> should point to a valid Log4j XML
configuration file. You can use all properties configured through the
Configurator in the XML configuration and reference the actual values.</p>


The document belongs to the following collections: cdocs-spring-configurator

View raw message