<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed 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>Turbine Services - Resources Service</title>
 </properties>

<body>

<section name="Resources Service">

<p>
Within Turbine was a service for reading and accessing data in Property
files. The classes that accomplish this have been borrowed from the
Apache JServ project, moved many time and finally ended up in the <a
href="http://jakarta.apache.org/commons/sandbox/configuration">commons-configuration</a>
 sub-project. So we removed the Service itself and now use commons-configuration everywhere.
</p>

</section>

<section name="Configuring Turbine">

<p>
Turbine gets its configuration file from the servlet container at
startup time. It is necessary to have an init parameter in the
servlet section of your web.xml file:
</p>

<source><![CDATA[
<init-param>
    <param-name>properties</param-name>
    <!-- This is relative to the docBase -->
    <param-value>
        /WEB-INF/conf/TurbineResources.properties
    </param-value>
</init-param>
]]></source>

</section>

<section name="Accessing properties">

<p>
Turbine post-2.2 uses commons-configuration all over the place, so if
you want to access properties files, you can use it in two ways.
</p>

<p>
Inside arbitrary code:
</p>

<source><![CDATA[
import org.apache.commons.configuration.Configuration;
import org.apache.turbine.Turbine;

//
// Access all properties from TurbineResource.properties
Configuration conf = Turbine.getConfiguration();

String myProperty = conf.getString("this.is.my.property");
]]></source>

<p>
Inside a service, you can easily access the already subclassed
property object for your service (that is, with the services.&lt;your service name&gt;
stripped away from the property:
</p>

<source><![CDATA[
public class myService extends TurbineBaseService
{
.
.
.
    Configuration conf = getConfiguration();
    String myProp = conf.getString("my.property"); // services.myService.my.property
.
.
.
}
]]></source>

</section>

</body>
</document>