Return-Path: Delivered-To: apmail-cocoon-docs-archive@www.apache.org Received: (qmail 60095 invoked from network); 11 Jan 2007 08:50:07 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 11 Jan 2007 08:50:07 -0000 Received: (qmail 49564 invoked by uid 500); 11 Jan 2007 08:50:14 -0000 Delivered-To: apmail-cocoon-docs-archive@cocoon.apache.org Received: (qmail 49423 invoked by uid 500); 11 Jan 2007 08:50:14 -0000 Mailing-List: contact docs-help@cocoon.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: docs@cocoon.apache.org List-Id: Delivered-To: mailing list docs@cocoon.apache.org Received: (qmail 49412 invoked by uid 99); 11 Jan 2007 08:50:14 -0000 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.67] (HELO cocoon.zones.apache.org) (140.211.11.67) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 11 Jan 2007 00:50:13 -0800 Message-ID: <32795541.1168505386882.JavaMail.daisy@cocoon.zones.apache.org> Date: Thu, 11 Jan 2007 08:49:46 +0000 (GMT+00:00) From: daisy@cocoon.zones.apache.org To: docs@cocoon.apache.org Subject: [DAISY] Created: Property Handling Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Virus-Checked: Checked by ClamAV on apache.org A new document has been created. http://cocoon.zones.apache.org/daisy/documentation/1310.html Document ID: 1310 Branch: main Language: default Name: Property Handling Document Type: Cocoon Document Created: 1/11/07 8:49:31 AM Creator (owner): Carsten Ziegeler State: publish Parts =3D=3D=3D=3D=3D Content ------- Mime type: text/xml Size: 10710 bytes Content:

The Cocoon Spring Configurator

The Spring Configurator is a useful component providing support in commo= n configuration issues when using the Spring framework. Although this product= has been developed inside the Cocoon project, it is aimed at making easier=C2= =A0the usage of Spring in each and every web application; it is not tied to the famous C= ocoon web application framework and can be used standalone. The impact on your co= de is nearly zero and the Spring Configurator=C2=A0as=C2=A0only Spring itself as = a dependency.

Motivation

When using a framework like Spring there are always the same problems to solve, like

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

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 the= re is more than one way of doing this and each and every project ends up developi= ng its own "proprietary" solution. A best practice and a standardized way of d= oing 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 configurat= ion issues with Spring. Ok, enough motivation, let's see what the Spring configurator can provide for your work.

Requirements

The Spring Configurator requires

  • the Spring Framework Version 2.0.1 (or above)
  • JDK 1.4 (or above)
  • Servlet API 2.3 (or above)

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:

TODO - Show dependency configuration

Configuration

The Spring Configurator uses the Spring the extensible XML authoring features and therefore it can be directly used in your Sp= ring bean configurations. Usually you add the configurator to your global web application context configuration (which is usually located at /WEB-INF/applicationContext.xml). The extensible XML authoring req= uires that you use the schema based configuration for Spring. Just add the requir= ed namespace definition, a reference to the configurator XML schema to your be= an configuration:

<beans xmlns=3D"http://www.springframework.org/schema/beans"
       xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
       xmlns:configurator=3D"http://cocoon.apache.org/schame/config=
urator"
       xsi:schemaLocation=3D"http://www.springframework.org/schema/beans ht=
tp://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                           http://cocoon.apache.org/schema/configur=
ator http://cocoon.apache.org/schema/configurator/cocoon-configurator-1.0.x=
sd">
    ...
</beans>

Then you can initialize the configurator by adding the settings element to your bean configuration:

   <!-- Activate Cocoon Spring Configurator -->
   <configurator:settings/>

And then...

Running Modes

The configurator provides the support of running modes. A runni= ng 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 configurati= ons and settings depending on the running mode.

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

The running mode can be set in two ways: you can either set it in your applicationContext.xml as a configuration for the settings element:

   <!-- Activate Cocoon Spring Configurator -->
   <configurator:settings runningMode=3D"test"/>

Or you can define the running mode by setting the system property org.apache.cocoon.mode on startup of your web application, usually= you do this by specifying -Dorg.apache.cocoon.mode=3Dtest when startin= g your application server. The system property has precedence over the value from = the application context. The default running mode is prod.

Property Configurations

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 requ= ired anymore. In addition the Configurator reads properties from various standar= d 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 are= a is very convenient for distributing properties within libraries, the second ar= ea is very easy to edit by administrators or developers.

Let's start with the full list of actions taken by the Spring Configurat= or to read in properties. During this process, various property files are read. I= f there is more than one definiton for a property, the last definition wins!<= /p>

  1. The classpath is scanned for property files inside jar files located at /META-INF/cocoon/properties/*.properties. Usually these property f= iles are default values for beans distributed with the jar the property files ar= e 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 t= hese property files are default values in the given running mode for beans distributed with the jar the property files are contained in. All these pro= perty 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 o= rder and all property files from the sub directory named [RUNNING_MODE] are read= in alphabetical order.
  9. If a property provider (see below) is configured in the application con= text, it is queried for a set of properties.
  10. Read additional configured properties from the settings configuration i= n the application context.
  11. Apply additional configured properties from the settigns configuration = in the application context.
  12. Apply system properties.

Although this list might look very scary, it is in fact a very simple bu= t 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 dire= ctory 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 val= ues 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 conf= igure them through a jndi context, you can provide these values through a custom implementation.

Configuring Log4j

You can use the Configurator to configure=C2=A0Log4j throu= gh an XML configuration file:

  <bean name=3D"org.apache.cocoon.spring.configurator.log4j"
        class=3D"org.apache.cocoon.spring.configurator.log4j.Log4JConfigura=
tor"
        scope=3D"singleton">
    <property name=3D"resource" value=3D"/WEB-INF/cocoon/log4j.xconf"/&g=
t;
  </bean>

The property resource 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.

Collections =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D The document belongs to the following collections: cdocs-spring-configurato= r