| <?xml version="1.0"?> |
| <!-- |
| /* |
| * Copyright 2001-2004 The Apache Software Foundation. |
| * |
| * Licensed 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 - Pull Service</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Pull Service"> |
| |
| <p> |
| The Pull service places tool objects in the Velocity context for use by |
| template engineers. It can handle tools with various different "scopes", |
| namely: |
| |
| <ul> |
| <li> |
| request-scope tools for which a new instance is needed for each |
| request. |
| </li> |
| |
| <li>global-scope tools for which a single instance can serve the |
| entire application. |
| </li> |
| |
| <li> |
| session-scope tools which are persisted as part of |
| the user object in the servlet engine provided session object. |
| </li> |
| |
| <li> |
| persistent-scope tools which are persisted as part of the user's |
| serialized object data. |
| </li> |
| </ul> |
| |
| </p> |
| |
| <p> |
| The service must be enabled in TurbineResources.properties as shown |
| below, and tools are listed there. The default properties file lists |
| some request-scope tools that are needed for basic Turbine usage |
| ($page, $link and $content), plus the useful UIManager global tool. |
| </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.PullService.classname=org.apache.turbine.services.pull.TurbinePullService |
| . |
| . |
| . |
| # ------------------------------------------------------------------- |
| # |
| # P U L L S E R V I C E |
| # |
| # ------------------------------------------------------------------- |
| # These are the properties for the Pull Service, the service |
| # that works in conjuction with the Turbine Pull Model API. |
| # ------------------------------------------------------------------- |
| |
| # This determines whether the non-request tools are refreshed |
| # on each request (request tools aren't ever, because they're |
| # instantiated for the request only anyway). |
| services.PullService.tools.per.request.refresh=true |
| |
| # These are tools that are placed in the context by the service |
| # These tools will be made available to all your |
| # templates. You list the tools in the following way: |
| # |
| # tool.<scope>.<id> = <classname> |
| # |
| # <scope> is the tool scope: global, request, session, |
| # authorized or persistent (see below for more details) |
| # <id> is the name of the tool in the context |
| # |
| # For example: |
| # |
| # tool.global.ui = org.apache.turbine.util.pull.UIManager |
| # tool.global.mm = org.apache.turbine.util.pull.MessageManager |
| # tool.request.link = org.apache.turbine.services.pull.tools.TemplateLink |
| # tool.request.page = org.apache.turbine.util.template.TemplatePageAttributes |
| # |
| # (the next two examples specify mythical classes) |
| # |
| # tool.session.basket = org.sample.tools.ShoppingBasket |
| # tool.persistent.ui = org.sample.tools.PersistentUIManager |
| # |
| # |
| # Tools are accessible in all templates by the <id> given |
| # to the tool. So for the above listings the UIManager would |
| # be available as $ui, the MessageManager as $mm, the TemplateLink |
| # as $link and the TemplatePageAttributes as $page. |
| # |
| # Scopes: |
| # |
| # global: tool is instantiated once and that instance is available |
| # to all templates for all requests. Tool must be threadsafe. |
| # |
| # request: tool is instantiated once for each request (although the |
| # PoolService is used to recycle instances). Tool need not |
| # be threadsafe. |
| # |
| # session: tool is instantiated once for each user session, and is |
| # stored in the user's temporary hashtable. Tool should be |
| # threadsafe. |
| # |
| # authorized: tool is instantiated once for each user session once the |
| # user logs in. After this, it is a normal session tool. |
| # |
| # persistent: tool is instantitated once for each user session once |
| # the user logs in and is is stored in the user's permanent |
| # hashtable. |
| # This means for a logged in user the tool will be persisted |
| # in the user's objectdata. Tool should be threadsafe and |
| # Serializable. |
| # |
| # Defaults: none |
| |
| tool.request.link=org.apache.turbine.services.pull.tools.TemplateLink |
| tool.request.page=org.apache.turbine.util.template.TemplatePageAttributes |
| tool.request.content=org.apache.turbine.services.pull.tools.ContentTool |
| #tool.request.om=org.apache.turbine.om.OMTool |
| #tool.request.intake=org.apache.turbine.services.intake.IntakeTool |
| |
| tool.global.ui=org.apache.turbine.services.pull.util.UIManager |
| |
| # The UI Manager will allow you to skin your Turbine |
| # application using simple properties files that are |
| # located in the WEBAPP/resources/ui/skins/ directory |
| # hierarchy. |
| |
| tool.ui.skin=default |
| |
| ]]></source> |
| |
| </section> |
| |
| <section name="Usage"> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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, authorized 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. |
| </p> |
| |
| <p> |
| Tools can implement the org.apache.turbine.services.pull.ApplicationTool |
| or the org.apache.turbine.services.pull.RunDataApplicationTool |
| 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. |
| </p> |
| |
| <p> |
| If you activate the RefreshToolsPerRequest property, every tool is |
| refreshed on each request. On Request Tools this makes no difference, |
| because here, the refresh() is never called (they're instantiated on |
| every request). All other scopes get a call to refresh() on every |
| request. If you chose to implement the RunDataApplicationTool interface, |
| you get the current RunData object passed to your tool. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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). |
| </p> |
| |
| </section> |
| |
| </body> |
| </document> |