xdocs/howto/configuration-howto.xml - turbine-core - Git at Google

 <?xml version="1.0"?>

 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <document>

 <properties>
     <title>Configuration Howto</title>
     <author email="epugh@upstate.com">Eric Pugh</author>
 </properties>

 <body>

 <section name="Configurating Turbine">
 <p>
 With Turbine 2.3, there are now two different ways to configure Turbine.  The old
 classic way was to provide a TurbineResources.properties file in the standard
 properties format.  However, added to 2.3 is the ability to specify an XML based
 TurbineConfiguration.xml file that instructs Turbine how to load properties from
 multiple sources.
 </p>
 </section>

 <section name="Why do I want multiple sources of configuration?">
 <p>
 In the classic development environment, the developer has one environment, there is
 a QA environment, and then production.  While all of these environments strive to be
 as similar as possible, there are often difference between them.  For instance, in
 the development environment, you might want to not have Turbine cache templates, that
 way, as you change them, they are just reloaded.  But in test and production you might
 need them to be non reloading for performance.  There are many other situations like this.
 </p>
 <p>
 This leads to complex build scripts where you try and customize properties based on what
 environment you are performing a build for.  The more complex the build is, the less frequently
 the development team performs them, which goes against Agile development principles.  The
 ability of Turbine to merge multiple configuration properties together allows developers to
 easily customize Turbine without resorting to complex build scripts.  A simple war:webapp is
 all you need for any environment!  Replacing something like build:dev, build:test, and build:live.
 </p>
 </section>

 <section name="Classic Configuration Using Single Property File">
 <p>
 The classic way of performing configuration is to provide the properties file via your
 web.xml file:
 </p>

 <source test=""><![CDATA[
     <servlet>
         <servlet-name>fortius</servlet-name>
         <servlet-class>org.apache.turbine.Turbine</servlet-class>
         <init-param>
             <param-name>properties</param-name>
                     <param-value>
                             /WEB-INF/conf/TurbineResources.properties
             </param-value>
         </init-param>

         <load-on-startup>1</load-on-startup>
     </servlet>
 ]]></source>

 <p>
 This works well, but if you want to customize the various settings that Turbine uses to
 control it's behavior, then you need to provide a TurbineConfiguration.xml file!
 </p>
 </section>

 <section name="TurbineConfiguration.xml File for Multiple Sources">
 <p>
 The TurbineConfiguration.xml file doesn't contain any configuration data itself, instead
 it points at other files that may have configuration data.  Turbine leverages Commons-Configuration's
 ConfigurationFactory to access the data.  For more information, look at
 <a href="http://commons.apache.org/configuration/">Configuration</a> homepage.
 </p>

 <p>
 To specify the location of your TurbineConfiguration.xml file, just change your servlet init
 parameters to this:
 </p>
 <source test=""><![CDATA[
     <servlet>
         <servlet-name>fortius</servlet-name>
         <servlet-class>org.apache.turbine.Turbine</servlet-class>
         <init-param>
             <param-name>configuration</param-name>
             <param-value>
                     /WEB-INF/conf/TurbineConfiguration.xml
             </param-value>
         </init-param>

         <load-on-startup>1</load-on-startup>
     </servlet>
 ]]>
 </source>

 <p>
 This file will contain lines like this:
 </p>

 <source test=""><![CDATA[
 <configuration>
   <jndi className="org.apache.commons.configuration.JNDIConfiguration" prefix="java:comp/env"/>
   <dom4j className="org.apache.commons.configuration.DOM4JConfiguration" fileName="/WEB-INF/conf/OtherProperties.xml"/>
   <properties className="org.apache.commons.configuration.PropertiesConfiguration" fileName="/WEB-INF/conf/TurbineResources.properties"/>
 </configuration>
 ]]></source>

 <p>
 The configurations specified first override the values of configurations specified
 afterwards.  So, if the configuration value "mail.server" is specified as mymailserver.mycompany.com in
 your JNDI settings, and localhost in the TurbineResources.properties, then when you issue:
 </p>
 <source>
 	String mailServer = Turbine.getConfiguration().get("mail.server");
 </source>
 <p>
 Then the mailServer value returned will be "mymailserver.mycompany.com".  However, if you
 don't have a setting specifed in your JNDI settings, then this would return "localhost".
 </p>

 </section>

 </body>
 </document>
	<?xml version="1.0"?>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<document>

	<properties>
	<title>Configuration Howto</title>
	<author email="epugh@upstate.com">Eric Pugh</author>
	</properties>

	<body>

	<section name="Configurating Turbine">
	<p>
	With Turbine 2.3, there are now two different ways to configure Turbine. The old
	classic way was to provide a TurbineResources.properties file in the standard
	properties format. However, added to 2.3 is the ability to specify an XML based
	TurbineConfiguration.xml file that instructs Turbine how to load properties from
	multiple sources.
	</p>
	</section>

	<section name="Why do I want multiple sources of configuration?">
	<p>
	In the classic development environment, the developer has one environment, there is
	a QA environment, and then production. While all of these environments strive to be
	as similar as possible, there are often difference between them. For instance, in
	the development environment, you might want to not have Turbine cache templates, that
	way, as you change them, they are just reloaded. But in test and production you might
	need them to be non reloading for performance. There are many other situations like this.
	</p>
	<p>
	This leads to complex build scripts where you try and customize properties based on what
	environment you are performing a build for. The more complex the build is, the less frequently
	the development team performs them, which goes against Agile development principles. The
	ability of Turbine to merge multiple configuration properties together allows developers to
	easily customize Turbine without resorting to complex build scripts. A simple war:webapp is
	all you need for any environment! Replacing something like build:dev, build:test, and build:live.
	</p>
	</section>

	<section name="Classic Configuration Using Single Property File">
	<p>
	The classic way of performing configuration is to provide the properties file via your
	web.xml file:
	</p>

	<source test=""><![CDATA[
	<servlet>
	<servlet-name>fortius</servlet-name>
	<servlet-class>org.apache.turbine.Turbine</servlet-class>
	<init-param>
	<param-name>properties</param-name>
	<param-value>
	/WEB-INF/conf/TurbineResources.properties
	</param-value>
	</init-param>

	<load-on-startup>1</load-on-startup>
	</servlet>
	]]></source>

	<p>
	This works well, but if you want to customize the various settings that Turbine uses to
	control it's behavior, then you need to provide a TurbineConfiguration.xml file!
	</p>
	</section>

	<section name="TurbineConfiguration.xml File for Multiple Sources">
	<p>
	The TurbineConfiguration.xml file doesn't contain any configuration data itself, instead
	it points at other files that may have configuration data. Turbine leverages Commons-Configuration's
	ConfigurationFactory to access the data. For more information, look at
	<a href="http://commons.apache.org/configuration/">Configuration</a> homepage.
	</p>

	<p>
	To specify the location of your TurbineConfiguration.xml file, just change your servlet init
	parameters to this:
	</p>
	<source test=""><![CDATA[
	<servlet>
	<servlet-name>fortius</servlet-name>
	<servlet-class>org.apache.turbine.Turbine</servlet-class>
	<init-param>
	<param-name>configuration</param-name>
	<param-value>
	/WEB-INF/conf/TurbineConfiguration.xml
	</param-value>
	</init-param>

	<load-on-startup>1</load-on-startup>
	</servlet>
	]]>
	</source>

	<p>
	This file will contain lines like this:
	</p>

	<source test=""><![CDATA[
	<configuration>
	<jndi className="org.apache.commons.configuration.JNDIConfiguration" prefix="java:comp/env"/>
	<dom4j className="org.apache.commons.configuration.DOM4JConfiguration" fileName="/WEB-INF/conf/OtherProperties.xml"/>
	<properties className="org.apache.commons.configuration.PropertiesConfiguration" fileName="/WEB-INF/conf/TurbineResources.properties"/>
	</configuration>
	]]></source>

	<p>
	The configurations specified first override the values of configurations specified
	afterwards. So, if the configuration value "mail.server" is specified as mymailserver.mycompany.com in
	your JNDI settings, and localhost in the TurbineResources.properties, then when you issue:
	</p>
	<source>
	String mailServer = Turbine.getConfiguration().get("mail.server");
	</source>
	<p>
	Then the mailServer value returned will be "mymailserver.mycompany.com". However, if you
	don't have a setting specifed in your JNDI settings, then this would return "localhost".
	</p>

	</section>

	</body>
	</document>