<?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>Pull Model Howto</title>
 </properties>

<body>

<section name="Using the pull model with Turbine 2">

<p>
Turbine 2 can be used with two different programming models - the push model
and the pull model.  The difference is in how the Context is built up.  The
Context is used by the Velocity or WebMacro template files to "fill in the
blanks" and introduce dynamic data into a static HTML-based template.  This
programming concept is incredibly powerful - because it allows the web
designer, who may be experienced with HTML, CSS, and Javascript but not
Java, to put data fields wherever they want on a page without having to ask
the Java programmers to change a Java class and recompile.  For more
information on which to choose for your Turbine application, read Jon
Stevens' informative commentary <a href="../pullmodel.html">Push vs
Pull</a>.
</p>

<p>
Also see the <a href="../services/pull-service.html">Pull Service</a>
Documentation
for another explanation of how the Pull Service works with Tools.
</p>

<p>
The push model is based on a one-to-one mapping of Java Screen
classes and Velocity template files.  The Screen class puts key/value pairs
into the Context.  The <a href="context-howto.html">Context Howto</a>
explains this approach.
</p>

<p>
The pull model allows the web designer even more freedom than the push
model. Java programmers can create globally accessible Java classes known as
Tools.   These Tools are going to be useful for getting data out of a
service and bringing it to the presentation layer, authenticating users, or
creating links (see the TemplateLink tool that is built into Turbine).
</p>
</section>

<section name="Pull Tool Implementation">
<p>
Your SimpleSecurityTool should implement ApplicationTool, which is a simple
interface with two methods, init(Object data) and refresh.  It could be a
facade class that calls other classes, or it could have its own business
logic.
</p>
</section>

<section name="Entries in TurbineResources.properties">
<p>
To make the Tool available to Turbine, you need to define your Tools in the
TurbineResources.properties file.  The "Pull Service" section of the
properties file is where the tools are listed.  You can use the following
syntax (all explained in the TurbineResources.properties):
</p>


<source><![CDATA[
tool.<Scope>.<Id> = <Classname>

tool.request.formsTool = com.yourcompany.turbine.tools.SimpleFormsTool
]]></source>

<p>
Classname is your java classname -
com.yourcompany.turbine.tools.SimpleFormsTool
</p>

<p>
Id is a unique identifier that you will use in your Velocity templates -
formsTool, for instance.
</p>

<p>
Scope defines the life cycle of the Tool.  There are four, global, request,
session, and persistent.
</p>

<p>
Global: The tool is instantiated once and is available to all templates for
all requests. Must be threadsafe.
</p>

<p>
Request: The tool is instantiated once for every request to Turbine.
Doesn't need to be threadsafe.  The link, page, and flux tools are all
defined as request scope.
</p>

<p>
Session: The tool is instantiated once for each user session. Should be
threadsafe.  Useful for tools that might hold user profiles, or items in a
shopping cart.
</p>

<p>
Persistent: Tool is instantiated once for each user session, and is stored
along with the user information.  Must be threadsafe and implement
Serializable.  An example of how this scope would be used would be great!
</p>

<p>
Additional tool-defined properties can be configured in the
TurbineResources.properties. The syntax is defined under the "Pull Service"
section.
</p>

</section>

</body>
</document>
