<?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>
</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! 
Reading from /WEB-INF/conf/TurbineResources.properties is actually the default fall back - if no init parameter is provided. 
</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
<code>DefaultConfigurationBuilder</code> to access the data.  For more information, look at
the <a href="http://commons.apache.org/proper/commons-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"/>
  <!-- CHANGE! As fileName is converted to URL internally now and applicationpath is prefixed fileName has to be a relative path, cft. RFC2396.  -->
  <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 specified in your JNDI settings, then this would return "localhost".
</p>

</section>

</body>
</document>
