A document has been updated:
http://cocoon.zones.apache.org/daisy/documentation/1309.html
Document ID: 1309
Branch: main
Language: default
Name: Running Modes (unchanged)
Document Type: Cocoon Document (unchanged)
Updated on: 1/11/07 8:51:20 AM
Updated by: Carsten Ziegeler
A new version has been created, state: publish
Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name: (unchanged)
Size: 1349 bytes (previous version: 10710 bytes)
Content diff:
<html>
<body>
--- <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>
---
--- <h2>Motivation</h2>
---
--- <p>When using a framework like Spring there are always the same problems to
--- solve, like</p>
---
--- <ul>
--- <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>
--- <li>How can I distribute partial web applications?</li>
--- <li>How do I manage hierarchial web application contexts?</li>
--- </ul>
---
--- <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>
---
--- <h2>Requirements</h2>
---
--- <p>The Spring Configurator requires</p>
---
--- <ul>
--- <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>
--- </ul>
---
--- <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>
---
--- <h2>Configuration</h2>
---
--- <p>The Spring Configurator uses the Spring the
--- <a
href="http://static.springframework.org/spring/docs/2.0.x/reference/new-in-2.html#new-in-2-ioc-custom-configuration";>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
--- configuration:</p>
---
--- <pre><beans xmlns="http://www.springframework.org/schema/beans";
--- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
---
<strong>xmlns:configurator="http://cocoon.apache.org/schame/configurator";</strong>
--- xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
---
<strong>http://cocoon.apache.org/schema/configurator
http://cocoon.apache.org/schema/configurator/cocoon-configurator-1.0.xsd";</strong>>
--- ...
--- </beans>
--- </pre>
---
--- <p>Then you can initialize the configurator by adding the <tt>settings</tt>
--- element to your bean configuration:</p>
---
--- <pre> <!-- Activate Cocoon Spring Configurator -->
--- <configurator:settings/>
--- </pre>
---
--- <p>And then...</p>
---
<h2>Running Modes</h2>
<p>The configurator provides the support of <em>running modes</em>. A
running
(21 equal lines skipped)
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="http://static.springframework.org/spring/docs/2.0.x/reference/beans.html#beans-factory-placeholderconfigurer";>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
--- locations.</p>
---
--- <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>
---
--- <ol>
--- <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
---
<tt>/WEB-INF/classes/META-INF/cocoon/properties/[RUNNING_MODE]/*.properties</tt>
--- 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/settings.properties</tt> file, this is read next.</li>
--- <li>If the system property <tt>org.apache.cocoon.settings</tt> 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.</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>
--- </ol>
---
--- <p>Although this list might look very scary, it is in fact a very simple but
--- powerful approach:</p>
---
--- <ul>
--- <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
--- /<tt>WEB-INF/classes/META-INF/cocoon/properties.</tt></li>
--- <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
--- <tt>/WEB-INF/cocoon/[RUNNING_MODE]/properties</tt>.</li>
--- <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
--- implementation.</li>
--- </ul>
---
--- <h2>Configuring Log4j</h2>
---
--- <p>You can use the Configurator to
--- configure <a href="http://logging.apache.org/log4j/";>Log4j</a> through an
XML
--- configuration file:</p>
---
--- <pre> <bean name="org.apache.cocoon.spring.configurator.log4j"
---
class="org.apache.cocoon.spring.configurator.log4j.Log4JConfigurator"
--- scope="singleton">
--- <property name="resource" value="/WEB-INF/cocoon/log4j.xconf"/>
--- </bean>
--- </pre>
---
--- <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>
---
</body>
</html>
