Also see the Pull Service Documentation for another explanation of how the Pull Service works with Tools.
The push model is found in the Flux/NewApp application that is distributed with the TDK 2.1. It 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 Context Howto explains this approach.
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).
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.
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):
tool.<Scope>.<Id> = <Classname> tool.request.formsTool = com.yourcompany.turbine.tools.SimpleFormsTool
Classname is your java classname - com.yourcompany.turbine.tools.SimpleFormsTool
Id is a unique identifier that you will use in your Velocity templates - formsTool, for instance.
Scope defines the life cycle of the Tool. There are four, global, request, session, and persistent.
Global: The tool is instantiated once and is available to all templates for all requests. Must be threadsafe.
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.
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.
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!
Additional tool-defined properties can be configured in the TurbineResources.properties. The syntax is defined under the "Pull Service" section.