The first step in use of the pull service is deciding on a useful
tool API for an object that is available to templates in the
Velocity context. This could range from something as simple as
the generation of URIs ($link and $content) to a tool for retrieving
details of the user's current shopping basket. Define a set of
public methods for the tool and they will be available through
standard Velocity introspection.
The next step is to decide what scope you need to give the tool.
If the tool is retrieving global data in a threadsafe manner, you
can make the tool global. If the tool holds data specific to the
user look at the session and persistent scopes (choose persistent
for a convenient way of having the tools fields persisted across
sessions for logged in users). If the tool needs to be instantiated
on each request to fulfill its function, or is not threadsafe, then
the request scope will be appropriate.
Tools can implement the org.apache.turbine.services.pull.ApplicationTool
interface. This will provide a hook for the service to initialise them
through the 'init' method and, except for request scope tools, to be
refreshed through the 'refresh' method. The type of the init argument
'data' (declared as type 'Object') depends on the scope of the tool.
For global tools the argument will be null; for session and persistent
scope tools, 'data' will be the current User object; and for request
scope tools 'data' will be the current RunData instance.
Important note: request scope tools are recycled by the PoolService.
This means they must be written to be reused. This usually means
implementing the ApplicationTool interface, and having the 'init'
implementation reset all fields.
Current examples of tools include the afore mentioned $link, $page and
$content objects, the $ui UI manager, the Intake service tool
(org.apache.turbine.services.intake.IntakeTool) and the OM tool
(org.apache.turbine.om.OMTool).