| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/howto/configuration-howto.xml at 10 Sep 2025 |
| | Rendered using Apache Maven Fluido Skin 2.1.0 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" /> |
| <title>Configuration Howto – Apache Turbine</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-2.1.0.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-2.1.0.min.js"></script> |
| <link rel="icon" type="image/png" sizes="48x48" href="https://apache.org/favicons/favicon.ico"> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <style>.github-fork-ribbon:before { background-color: orange; }</style> |
| </head> |
| <body> |
| <a class="github-fork-ribbon right-top" href="https://github.com/apache/turbine-build" data-ribbon="Fork me on GitHub">Fork me on GitHub</a> |
| <div class="container-fluid container-fluid-top"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><div id="bannerLeft"><h1><a href="https://turbine.apache.org/"><img src="https://www.apache.org/img/feather_glyph_notm.png" style="width: 50px;" /> The Apache Turbine project</a></h1></div></div> |
| <div class="pull-right"><div id="bannerRight"><h1><a href="https://turbine.apache.org/"><img src="https://turbine.apache.org/images/logo.gif" alt="Apache Turbine" /></a></h1></div></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 01 Apr 2025<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 7.1-SNAPSHOT</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://turbine.apache.org/fulcrum/">Fulcrum</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://turbine.apache.org/">Turbine</a></li> |
| <li class="pull-right"><a href="https://www.apache.org">Apache</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">General Information</li> |
| <li><a href="../index.html">Overview</a></li> |
| <li><a href="../features.html">Features</a></li> |
| <li><a href="../fsd.html">Specification</a></li> |
| <li><a href="../getting-started.html">Getting Started</a></li> |
| <li><a href="../how-to-build.html">Howto Build Turbine</a></li> |
| <li><a href="../changes-report.html">Changes</a></li> |
| <li class="nav-header">Documentation</li> |
| <li><a href="../services/index.html"><span class="icon-chevron-right"></span>Services</a></li> |
| <li><a href="../howto/index.html"><span class="icon-chevron-down"></span>Howtos</a> |
| <ul class="nav nav-list"> |
| <li><a href="../howto/action-event-howto.html">Action Events Howto</a></li> |
| <li><a href="../howto/annotations.html">Annotations Howto</a></li> |
| <li class="active"><a>Configuration Howto</a></li> |
| <li><a href="../howto/extend-user-howto.html">Extend User Howto</a></li> |
| <li><a href="../howto/hibernate-howto.html">Hibernate OM Howto</a></li> |
| <li><a href="../howto/intake-howto.html">Intake Howto</a></li> |
| <li><a href="../howto/jsp-howto.html">JSP Howto</a></li> |
| <li><a href="../howto/migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li> |
| <li><a href="../howto/migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li> |
| <li><a href="../howto/migrate-from-2_3-howto.html">Migrating from 2.3 to 4.0</a></li> |
| <li><a href="../howto/migrate-from-4_0-howto.html">Migrating from 4.0 to 5.0</a></li> |
| <li><a href="../howto/pullmodel-howto.html">Pull Model Howto</a></li> |
| <li><a href="../howto/python-howto.html">Python Howto</a></li> |
| <li><a href="../howto/security-howto.html">Security Howto</a></li> |
| <li><a href="../howto/services-howto.html">Services Howto</a></li> |
| <li><a href="../howto/url-mapper-howto.html">URL Mapper Howto</a></li> |
| <li><a href="../howto/url-rewriting-howto.html">URL Rewriting Howto</a></li> |
| <li><a href="../howto/context-howto.html">Velocity Context Howto</a></li> |
| <li><a href="../howto/velocity-site-howto.html">Velocity Site Howto</a></li> |
| <li><a href="../howto/velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a></li> |
| </ul></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/TURBINE">Wiki</a></li> |
| <li><a href="../apidocs/index.html">JavaDocs</a></li> |
| <li class="nav-header">Development</li> |
| <li><a href="../proposals.html">Proposals</a></li> |
| <li><a href="../how-to-help.html">How To Help</a></li> |
| <li><a href="../todo.html">Todo</a></li> |
| <li class="nav-header">Project Documentation</li> |
| <li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li> |
| <li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li> |
| <li class="nav-header">Apache</li> |
| <li><a href="https://www.apache.org/">Apache Website</a></li> |
| <li><a href="https://www.apache.org/licenses/">License</a></li> |
| <li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| <li><a href="https://www.apache.org/security/">Security</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <form id="search-form" action="https://www.google.com/search" method="get" > |
| <input value="http://turbine.apache.org/turbine/turbine-7-0" name="sitesearch" type="hidden" /> |
| <input class="search-query" name="q" id="query" type="text" placeholder="Search with Google..." /> |
| </form> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10"> |
| |
| |
| |
| |
| <section><a id="Configurating_Turbine"></a> |
| <h1>Configurating Turbine</h1> |
| |
| <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><a id="Why_do_I_want_multiple_sources_of_configuration.3F"></a> |
| <h1>Why do I want multiple sources of configuration?</h1> |
| |
| <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><a id="Classic_Configuration_Using_Single_Property_File"></a> |
| <h1>Classic Configuration Using Single Property File</h1> |
| |
| <p> |
| The classic way of performing configuration is to provide the properties file via your |
| web.xml file: |
| </p> |
| |
| |
| <pre class="prettyprint"><code> |
| <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> |
| </code></pre> |
| |
| |
| <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><a id="TurbineConfiguration.xml_File_for_Multiple_Sources"></a> |
| <h1>TurbineConfiguration.xml File for Multiple Sources</h1> |
| |
| <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/" class="externalLink">Configuration</a> |
| homepage. |
| </p> |
| |
| |
| <p> |
| To specify the location of your TurbineConfiguration.xml file, just change your servlet init |
| parameters to this: |
| </p> |
| |
| <pre class="prettyprint"><code> |
| <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> |
| |
| </code></pre> |
| |
| |
| <p> |
| This file will contain lines like this: |
| </p> |
| |
| |
| <pre class="prettyprint"><code> |
| <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> |
| </code></pre> |
| |
| |
| <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> |
| |
| <pre class="prettyprint"><code> |
| String mailServer = Turbine.getConfiguration().get("mail.server"); |
| </code></pre> |
| |
| <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> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>© 2000–2025 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a> |
| </p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
