extensions/maven-plugin/xdocs/config.xml - turbine-core - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  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 files reference</title>
     <author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
   </properties>

   <body>

   <section name="Configuration files">
   <p>
   M.E.T.A. generates a few configuration files for your application. These work
   well for a simple application without security and just a few data sources.<br/>
   <b>All configuration files, unless stated explicitly otherwise, get
   deleted and recreated if you re-run <code>turbine:setup</code>. So be
   careful!</b>
   </p>

 <subsection name="Maven specific configuration files">
 <p>
 M.E.T.A. generates and uses the following configuration files in the root
 directory of your application tree.<br/>

 If you run the <code>turbine:setup</code> goal and no
 <code>setup.properties</code> file exists in it, a new file is
 created with all parameters copied in. An existing setup.properties
 file is never clobbered!<br/>

 <table>
   <tr>
     <th>Name</th>
     <th>Function</th>
     <th>Description</th>
   </tr>
   <tr>
     <a name="setup_properties"/>
     <td>setup.properties</td>
     <td>M.E.T.A. configuration</td>
     <td>Whenever you run the <code>turbine:setup</code> goal, this
         file is read and used to generate all other configuration
         files. It should contain the <a
         href="properties.html#setup_properties">Setup Properties</a> for
         generating you application skeleton.</td>
   </tr>
   <tr>
     <td>build.properties</td>
     <td>Application configuration</td>
     <td>This file is intended to customize your application for a specific installation.</td>
   </tr>
     <a name="project_properties"/>
   <tr>
     <td>project.properties</td>
     <td>Application configuration</td>
     <td>This file is intended to configure your application. It should contain the properties that
         are the same for all installations.</td>
   </tr>
   <tr>
     <td>maven.xml</td>
     <td>Maven build file</td>
     <td>This file contains the callbacks from other maven goals into
         M.E.T.A. If you need to customize your build process, you can add
         custom goals or callbacks in this file.</td>
   </tr>
   <tr>
     <td>project.xml</td>
     <td>Maven POM file</td>
     <td>This file contains the maven-specific <a
         href="http://maven.apache.org/reference/project-descriptor.html">Project
         descriptor</a>.</td>
   </tr>
   </table>
   </p>
   </subsection>

   <subsection name="Application specific configuration files">
   <p>
   M.E.T.A. generates the following configuration files for your
   application. These location of these files differ in the various
   application development modes.

   <table>
   <tr>
     <th>Name and Location in normal Mode</th>
     <th>name and Location in inplace Mode</th>
     <th>Function</th>
     <th>Description</th>
   </tr>
   <tr>
     <td>conf/&lt;appname&gt;.properties</td>
     <td>WEB-INF/conf/&lt;appname&gt;.properties</td>
     <td>Turbine configuration</td>
     <td>This file gets included by the <code>TurbineResources.properties</code> file when Turbine is configured.</td>
   </tr>
   <tr>
     <td>conf/&lt;appname&gt;-web.xml</td>
     <td>WEB-INF/web.xml</td>
     <td>Deployment descriptor</td>
     <td>This is the deployment descriptor for your application. In <a href="modes.html#normal">Normal</a> mode, it gets copied to <code>WEB-INF/web.xml</code> in your application.</td>
   </tr>
   <tr>
     <td>conf/&lt;appname&gt;-intake.xml</td>
     <td>WEB-INF/conf/&lt;appname&gt;-intake.xml</td>
     <td>IntakeService</td>
     <td>This file should contain your intake group definitions.</td>
   </tr>
   </table>
   </p>
   </subsection>

   <subsection name="TurbineResource.properties">
   <p>
   This is the main configuration file for Tubine. It contains all the
   settings for the turbine core. The M.E.T.A. configuration has the
   following settings which might bite you when you build an
   application. It is necessary that you review the settings in this
   file and customize them to match your application needs!<br/> This
   list is not complete. The full list can be reviewed in the
   <code>TurbineResources.properties</code> file itself.
   </p>

   <table>
   <tr>
     <th>Setting</th>
     <th>Value</th>
     <th>Description</th>
   </tr>
   <tr>
     <td>module.packages</td>
     <td>org.apache.turbine.modules</td>

     <td>Contains only the internal package and not the application
         package. This is loaded from the &lt;appname&gt;.properties
         file. Unlike normal properties files, Turbine uses
         ExtendedProperties from <a
         href="http://commons.apache.org/configuration/">Jakarta
         Commons Configuration</a> which merge together (normal
         Properties would overwrite, so this might be confusing to
         newcomers). If you add your own packages to your application
         tree, do it in &lt;appname&gt;.properties.
     </td>
   </tr>
   <tr>
     <td>action.sessionvalidator</td>
     <td>sessionvalidator.TemplateSessionValidator</td>
     <td>A M.E.T.A.-generated application does not use security by default! If you
     need <a
     href="http://www.lyricsdir.com/m/men-without-hats/security-everybody-feels-better-with.php">security</a>,
     you must change this to
     <code>sessionvalidator.TemplateSecureSessionValidator</code>.
     </td>
   </tr>
   <tr>
     <td>services.*</td>
     <td colspan="2">The default configuration does not activate all
 the Turbine-supplied services! E.g. the Scheduler is not activated by
 default. If you need additional services, you must add them to your
 configuration file. M.E.T.A. activates the following services:<br/>
 <ul>
 <li>AvalonComponentService</li>
 <li>CryptoService</li>
 <li>FactoryService</li>
 <li>PoolService</li>
 <li>RunDataService</li>
 <li>ServletService</li>
 <li>AssemblerBrokerService</li>
 <li>GlobalCacheService</li>
 <li>SecurityService</li>
 <li>PullService</li>
 <li>IntakeService</li>
 <li>TemplateService</li>
 <li>VelocityService</li>
 <li>UploadService</li>
 </ul>
 </td>
   </tr>
   <tr>
     <td>tool.content.want.relative<br/>tool.link.want.relative</td>
     <td>true</td>
     <td>The tools generate relative links to avoid problems with some
     web containers. If you need absolute links, you must change these
     settings.</td>
   </tr>
   <tr>
     <td>services.VelocityService.default.screen</td>
     <td>VelocityScreen</td>
     <td>Use a screen class that does no security checks as default.</td>
   </tr>
   <tr>
     <td>services.VelocityService.velocimacro.library.autoreload</td>
     <td>true</td>
     <td>Good for debugging, bad for production. If your macro files no longer change, set this to false.</td>
   </tr>
   <tr>
     <td>services.IntakeService.serialize.path</td>
     <td>none</td>
     <td>Don't serialize the intake XML files. Good for debugging, bad for performance.</td>
   <tr>
     <td>include</td>
     <td>&lt;appname&gt;.properties</td>
     <td>Load an additional configuration file and merge it into the main configuration.</td>
   </tr>
   </tr>
   </table>
   </subsection>

   <subsection name="Application-specific properties">
   <p>
   All application specific parameters are configured in &lt;appname&gt;.properties. This file is
   loaded by an <code>include</code> property in <code>TurbineResources.properties</code>.
   </p>

   <table>
   <tr>
     <th>Setting</th>
     <th>Value</th>
     <th>Description</th>
   </tr>

   <tr>
     <td>module.packages</td>
     <td>org.apache.turbine.app.&lt;appname&gt;.modules</td>
     <td>Package path for the application specific modules</td>
   </tr>
   <tr>
     <td>services.VelocityService.velocimacro.library</td>
     <td>macros/&lt;appname&gt;Macros.vm</td>
     <td>Load application macros into Velocity Service.</td>
   </tr>
   <tr>
     <td>services.IntakeService.xml.path</td>
     <td>WEB-INF/conf/helloworld-intake.xml</td>
     <td>Application specific intake file.</td>
   </tr>
   </table>
   </subsection>

   <subsection name="torque.properties">
   <p>
   Some parts of Turbine and probably your web application might use
   <a href="http://db.apache.org/torque/">Torque</a> to access databases.<br/>
   In this configuration file, the various datasources are defined. M.E.T.A.
   generates a default data source (<code>default</code>) and an application
   specific data source (<code>&lt;appname&gt;</code>) for you.<br/>
   At setup time, both data sources are mapped onto the same JDBC data provider.
   </p>

   <p>M.E.T.A. configures Torque to use the
   <code>org.apache.torque.dsfactory.SharedPoolDataSourceFactory</code>
   as pool factory.</p>
   </subsection>

   <subsection name="log4j.properties">
   <p>
   For debugging purposes is it very important to get logging
   information from a running application. M.E.T.A. generated applications
   write the following log files into the <a
   href="tree.html#logs">logs</a> subdirectory:<br/>

 <table>
 <tr>
 <th>Log file</th><th>classes</th><th>Description</th>
 </tr>
 <tr>
 <td>turbine.log</td>
 <td>org.apache.turbine</td>
 <td>Log messages from the Turbine core</td>
 </tr>
 <tr>
 <td>torque.log</td>
 <td>org.apache.torque</td>
 <td>Torque logging</td>
 </tr>
 <tr>
 <td>scheduler.log</td>
 <td>SchedulerService</td>
 <td>Reports and logging from the scheduler</td>
 </tr>
 <tr>
 <td>velocity.log</td>
 <td>VelocityService</td>
 <td>Velocity messages</td>
 </tr>
 <tr>
 <td>avalon.log</td>
 <td>AvalonService</td>
 <td>Avalon components (if they don't use their own logging)</td>
 </tr>
 <tr>
 <td>application.log</td>
 <td><a href="properties.html#turbine_app_package">${turbine.app.package}</a><br/>
     Everything else</td>
 <td>Catchall category. Your application logs its messages here</td>
 </tr>
   </table>
 </p>
 </subsection>

   <subsection name="Avalon specific configuration">
   <p>
   Turbine 2.3 uses the AvalonComponentService to load and initialize
   <a href="http://db.apache.org/torque/">Torque</a>.<br/>
   M.E.T.A. provides two
   minimal <a href="http://avalon.apache.org/">Avalon</a> configuration
   files to allow this:

   <ul>
     <li>componentConfiguration.xml</li>
     <li>roleConfiguration.xml</li>
   </ul>

   If you don't intend to use Avalon in your application, you should
   not change anything here.</p>
   </subsection>
   <p><font color="red">Using M.E.T.A. is no replacement for looking at the Turbine documentation and the
   comments in the configuration files!</font></p>
 </section>
 </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	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 files reference</title>
	<author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
	</properties>

	<body>

	<section name="Configuration files">
	<p>
	M.E.T.A. generates a few configuration files for your application. These work
	well for a simple application without security and just a few data sources.<br/>
	<b>All configuration files, unless stated explicitly otherwise, get
	deleted and recreated if you re-run <code>turbine:setup</code>. So be
	careful!</b>
	</p>

	<subsection name="Maven specific configuration files">
	<p>
	M.E.T.A. generates and uses the following configuration files in the root
	directory of your application tree.<br/>

	If you run the <code>turbine:setup</code> goal and no
	<code>setup.properties</code> file exists in it, a new file is
	created with all parameters copied in. An existing setup.properties
	file is never clobbered!<br/>

	<table>
	<tr>
	<th>Name</th>
	<th>Function</th>
	<th>Description</th>
	</tr>
	<tr>
	<a name="setup_properties"/>
	<td>setup.properties</td>
	<td>M.E.T.A. configuration</td>
	<td>Whenever you run the <code>turbine:setup</code> goal, this
	file is read and used to generate all other configuration
	files. It should contain the <a
	href="properties.html#setup_properties">Setup Properties</a> for
	generating you application skeleton.</td>
	</tr>
	<tr>
	<td>build.properties</td>
	<td>Application configuration</td>
	<td>This file is intended to customize your application for a specific installation.</td>
	</tr>
	<a name="project_properties"/>
	<tr>
	<td>project.properties</td>
	<td>Application configuration</td>
	<td>This file is intended to configure your application. It should contain the properties that
	are the same for all installations.</td>
	</tr>
	<tr>
	<td>maven.xml</td>
	<td>Maven build file</td>
	<td>This file contains the callbacks from other maven goals into
	M.E.T.A. If you need to customize your build process, you can add
	custom goals or callbacks in this file.</td>
	</tr>
	<tr>
	<td>project.xml</td>
	<td>Maven POM file</td>
	<td>This file contains the maven-specific <a
	href="http://maven.apache.org/reference/project-descriptor.html">Project
	descriptor</a>.</td>
	</tr>
	</table>
	</p>
	</subsection>

	<subsection name="Application specific configuration files">
	<p>
	M.E.T.A. generates the following configuration files for your
	application. These location of these files differ in the various
	application development modes.

	<table>
	<tr>
	<th>Name and Location in normal Mode</th>
	<th>name and Location in inplace Mode</th>
	<th>Function</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>conf/<appname>.properties</td>
	<td>WEB-INF/conf/<appname>.properties</td>
	<td>Turbine configuration</td>
	<td>This file gets included by the <code>TurbineResources.properties</code> file when Turbine is configured.</td>
	</tr>
	<tr>
	<td>conf/<appname>-web.xml</td>
	<td>WEB-INF/web.xml</td>
	<td>Deployment descriptor</td>
	<td>This is the deployment descriptor for your application. In <a href="modes.html#normal">Normal</a> mode, it gets copied to <code>WEB-INF/web.xml</code> in your application.</td>
	</tr>
	<tr>
	<td>conf/<appname>-intake.xml</td>
	<td>WEB-INF/conf/<appname>-intake.xml</td>
	<td>IntakeService</td>
	<td>This file should contain your intake group definitions.</td>
	</tr>
	</table>
	</p>
	</subsection>

	<subsection name="TurbineResource.properties">
	<p>
	This is the main configuration file for Tubine. It contains all the
	settings for the turbine core. The M.E.T.A. configuration has the
	following settings which might bite you when you build an
	application. It is necessary that you review the settings in this
	file and customize them to match your application needs!<br/> This
	list is not complete. The full list can be reviewed in the
	<code>TurbineResources.properties</code> file itself.
	</p>

	<table>
	<tr>
	<th>Setting</th>
	<th>Value</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>module.packages</td>
	<td>org.apache.turbine.modules</td>

	<td>Contains only the internal package and not the application
	package. This is loaded from the <appname>.properties
	file. Unlike normal properties files, Turbine uses
	ExtendedProperties from <a
	href="http://commons.apache.org/configuration/">Jakarta
	Commons Configuration</a> which merge together (normal
	Properties would overwrite, so this might be confusing to
	newcomers). If you add your own packages to your application
	tree, do it in <appname>.properties.
	</td>
	</tr>
	<tr>
	<td>action.sessionvalidator</td>
	<td>sessionvalidator.TemplateSessionValidator</td>
	<td>A M.E.T.A.-generated application does not use security by default! If you
	need <a
	href="http://www.lyricsdir.com/m/men-without-hats/security-everybody-feels-better-with.php">security</a>,
	you must change this to
	<code>sessionvalidator.TemplateSecureSessionValidator</code>.
	</td>
	</tr>
	<tr>
	<td>services.*</td>
	<td colspan="2">The default configuration does not activate all
	the Turbine-supplied services! E.g. the Scheduler is not activated by
	default. If you need additional services, you must add them to your
	configuration file. M.E.T.A. activates the following services:<br/>
	<ul>
	<li>AvalonComponentService</li>
	<li>CryptoService</li>
	<li>FactoryService</li>
	<li>PoolService</li>
	<li>RunDataService</li>
	<li>ServletService</li>
	<li>AssemblerBrokerService</li>
	<li>GlobalCacheService</li>
	<li>SecurityService</li>
	<li>PullService</li>
	<li>IntakeService</li>
	<li>TemplateService</li>
	<li>VelocityService</li>
	<li>UploadService</li>
	</ul>
	</td>
	</tr>
	<tr>
	<td>tool.content.want.relative<br/>tool.link.want.relative</td>
	<td>true</td>
	<td>The tools generate relative links to avoid problems with some
	web containers. If you need absolute links, you must change these
	settings.</td>
	</tr>
	<tr>
	<td>services.VelocityService.default.screen</td>
	<td>VelocityScreen</td>
	<td>Use a screen class that does no security checks as default.</td>
	</tr>
	<tr>
	<td>services.VelocityService.velocimacro.library.autoreload</td>
	<td>true</td>
	<td>Good for debugging, bad for production. If your macro files no longer change, set this to false.</td>
	</tr>
	<tr>
	<td>services.IntakeService.serialize.path</td>
	<td>none</td>
	<td>Don't serialize the intake XML files. Good for debugging, bad for performance.</td>
	<tr>
	<td>include</td>
	<td><appname>.properties</td>
	<td>Load an additional configuration file and merge it into the main configuration.</td>
	</tr>
	</tr>
	</table>
	</subsection>

	<subsection name="Application-specific properties">
	<p>
	All application specific parameters are configured in <appname>.properties. This file is
	loaded by an <code>include</code> property in <code>TurbineResources.properties</code>.
	</p>

	<table>
	<tr>
	<th>Setting</th>
	<th>Value</th>
	<th>Description</th>
	</tr>

	<tr>
	<td>module.packages</td>
	<td>org.apache.turbine.app.<appname>.modules</td>
	<td>Package path for the application specific modules</td>
	</tr>
	<tr>
	<td>services.VelocityService.velocimacro.library</td>
	<td>macros/<appname>Macros.vm</td>
	<td>Load application macros into Velocity Service.</td>
	</tr>
	<tr>
	<td>services.IntakeService.xml.path</td>
	<td>WEB-INF/conf/helloworld-intake.xml</td>
	<td>Application specific intake file.</td>
	</tr>
	</table>
	</subsection>

	<subsection name="torque.properties">
	<p>
	Some parts of Turbine and probably your web application might use
	<a href="http://db.apache.org/torque/">Torque</a> to access databases.<br/>
	In this configuration file, the various datasources are defined. M.E.T.A.
	generates a default data source (<code>default</code>) and an application
	specific data source (<code><appname></code>) for you.<br/>
	At setup time, both data sources are mapped onto the same JDBC data provider.
	</p>

	<p>M.E.T.A. configures Torque to use the
	<code>org.apache.torque.dsfactory.SharedPoolDataSourceFactory</code>
	as pool factory.</p>
	</subsection>

	<subsection name="log4j.properties">
	<p>
	For debugging purposes is it very important to get logging
	information from a running application. M.E.T.A. generated applications
	write the following log files into the <a
	href="tree.html#logs">logs</a> subdirectory:<br/>

	<table>
	<tr>
	<th>Log file</th><th>classes</th><th>Description</th>
	</tr>
	<tr>
	<td>turbine.log</td>
	<td>org.apache.turbine</td>
	<td>Log messages from the Turbine core</td>
	</tr>
	<tr>
	<td>torque.log</td>
	<td>org.apache.torque</td>
	<td>Torque logging</td>
	</tr>
	<tr>
	<td>scheduler.log</td>
	<td>SchedulerService</td>
	<td>Reports and logging from the scheduler</td>
	</tr>
	<tr>
	<td>velocity.log</td>
	<td>VelocityService</td>
	<td>Velocity messages</td>
	</tr>
	<tr>
	<td>avalon.log</td>
	<td>AvalonService</td>
	<td>Avalon components (if they don't use their own logging)</td>
	</tr>
	<tr>
	<td>application.log</td>
	<td><a href="properties.html#turbine_app_package">${turbine.app.package}</a><br/>
	Everything else</td>
	<td>Catchall category. Your application logs its messages here</td>
	</tr>
	</table>
	</p>
	</subsection>

	<subsection name="Avalon specific configuration">
	<p>
	Turbine 2.3 uses the AvalonComponentService to load and initialize
	<a href="http://db.apache.org/torque/">Torque</a>.<br/>
	M.E.T.A. provides two
	minimal <a href="http://avalon.apache.org/">Avalon</a> configuration
	files to allow this:

	<ul>
	<li>componentConfiguration.xml</li>
	<li>roleConfiguration.xml</li>
	</ul>

	If you don't intend to use Avalon in your application, you should
	not change anything here.</p>
	</subsection>
	<p><font color="red">Using M.E.T.A. is no replacement for looking at the Turbine documentation and the
	comments in the configuration files!</font></p>
	</section>
	</body>
	</document>