Using the pull model with Turbine 2
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 Push vs Pull.
Also see the Pull Service Documentation for another explanation of how the Pull Service works with Tools.
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 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).
Pull Tool Implementation
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.
Entries in TurbineResources.properties
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.