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 ===== Content ------- Mime type: text/xml Size: 10710 bytes Content: <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 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 </tt>element:</p> <pre> <!-- Activate Cocoon Spring Configurator --> <configurator:settings runningMode="test"/> </pre> <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="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> Collections =========== The document belongs to the following collections: cdocs-spring-configurator
