| <?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> |