<?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 - Avalon Component Service</title>
 </properties>

<body>

<section name="Avalon Component Service">
<p>
The Avalon Component service loads external modules which implement the
<a href="http://avalon.apache.org/">Avalon</a> lifecycle interfaces.
</p>
<p>
The only supported component at this point in time is 
<a href="http://db.apache.org/torque/">Torque</a>, though the
<a href="http://jakarta.apache.org/turbine/fulcrum/">Fulcrum</a>
components are likely to be migrated to become Avalon components 
in the future.
</p>

</section>

<section name="Dependencies">

<p>
Don't forget to update the dependencies of your project to match
those defined for Turbine and the components you are loading:
<ul>
<li><a href="../dependencies.html">Turbine Dependencies</a></li>
<li><a href="http://db.apache.org/torque/dependencies.html">Torque Dependencies</a></li>
</ul>
</p>

</section>

<section name="Configuration">

	<source><![CDATA[
# -------------------------------------------------------------------
# 
#  S E R V I C E S
#
# -------------------------------------------------------------------
# Classes for Turbine Services should be defined here.
# Format: services.[name].classname=[implementing class]
#
# To specify properties of a service use the following syntax:
# service.[name].[property]=[value]

services.AvalonComponentService.classname = org.apache.turbine.services.avaloncomponent.TurbineAvalonComponentService
.
.
.
# -------------------------------------------------------------------
#
#  A V A L O N   C O M P O N E N T   S E R V I C E
#
# -------------------------------------------------------------------
# Components implementing the avalon lifecycle interfaces can be 
# loaded, configured and initialized by Turbine
# -------------------------------------------------------------------

services.AvalonComponentService.componentConfiguration = /WEB-INF/conf/componentConfiguration.xml
services.AvalonComponentService.componentRoles = /WEB-INF/conf/roleConfiguration.xml
services.AvalonComponentService.lookup = org.apache.torque.avalon.Torque
]]></source>
<p>
In /WEB-INF/conf you should provide componentConfiguration.xml:
</p>
<source><![CDATA[
<componentConfig>
    <torque>
       <configfile>/WEB-INF/conf/torque.properties</configfile>
    </torque>
</componentConfig>
]]></source>
<p>
and roleConfiguration.xml:
</p>
<source><![CDATA[
<role-list>
    <role name="org.apache.torque.avalon.Torque"
          shorthand="torque"
          default-class="org.apache.torque.avalon.TorqueComponent" />
</role-list>
]]></source>
<p>
No changes to torque.properties are required.
</p>
<p>
If all goes well you should see the following in your log file when 
Turbine starts up:
</p>
<source><![CDATA[
...INFO...services.BaseServiceBroker - Added Mapping for Service: AvalonComponentService
...INFO...services.BaseServiceBroker - Start Initializing service (early): AvalonComponentService
...INFO...services.avaloncomponent.TurbineAvalonComponentService - Lookup for Component org.apache.torque.avalon.Torque successful
...INFO...services.BaseServiceBroker - Finish Initializing service (early): AvalonComponentService
]]></source>

</section>

<section name="Usage">

<p>
If you plan to use the decoupled Torque in your application, you should
leave the Avalon Component Service configured at all times. It is started at
early startup time. Once it has initialized all the components, there
are no application specific methods or services available.
</p>
</section>

</body>

</document>