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.
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.
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.
The classic way of performing configuration is to provide the properties file via your web.xml file:
<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>
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.
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 DefaultConfigurationBuilder to access the data. For more information, look at the Configuration homepage.
To specify the location of your TurbineConfiguration.xml file, just change your servlet init parameters to this:
<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>
This file will contain lines like this:
<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>
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:
String mailServer = Turbine.getConfiguration().get("mail.server");
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".