<?xml version="1.0"?>
<!--
 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>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://turbine.apache.org/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>
