org.apache.turbine.services.pull
Class TurbinePullService

java.lang.Object
  |
  +--org.apache.turbine.services.BaseInitable
        |
        +--org.apache.turbine.services.BaseService
              |
              +--org.apache.turbine.services.TurbineBaseService
                    |
                    +--org.apache.turbine.services.pull.TurbinePullService
All Implemented Interfaces:
Initable, PullService, Service

public class TurbinePullService
extends TurbineBaseService
implements PullService

This is the concrete implementation of the Turbine Pull Service.

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.. = 

       is the tool scope: global, request, session
             or persistent (see below for more details)
          is the name of the tool in the context

 You can configure the tools in this way:
 tool.. = 

 So if you find "global", "request", "session" or "persistent" as second
 part, it is a configuration to put a tool into the toolbox, else it is a
 tool specific configuration.

 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.util.template.TemplateLink
 tool.request.page = org.apache.turbine.util.template.TemplatePageAttributes

 Then:

 tool.ui.skin = default

 configures the value of "skin" for the "ui" tool.

 Tools are accessible in all templates by the  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.

 You should avoid using tool names called "global", "request",
 "session" or "persistent" because of clashes with the possible Scopes.

 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.

  persistent: tool is instantitated once for each use session, and
              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
 

Version:
$Id: TurbinePullService.java,v 1.4 2001/09/17 17:17:28 dlr Exp $
Author:
Jason van Zyl, Sean Legassick

Inner Class Summary
private static class TurbinePullService.ToolData
          This inner class is used in the lists below to store the tool name and class for each of request, session and persistent tools
 
Field Summary
private static java.lang.String absolutePathToResourcesDirectory
          The absolute path the to resources directory used by the application tools.
private static java.lang.String GLOBAL_TOOL
          The property tags that are used in conjunction with TurbineResources.getOrderedValues(String) to get our list of tools to instantiate (one tag for each type of tool).
private  org.apache.velocity.context.Context globalContext
          This is the container for the global web application tools that are used in conjunction with the Turbine Pull Model.
private  java.util.List globalTools
          The lists that store tool data (name and class) for each of the different type of tool.
private static java.lang.String PERSISTENT_TOOL
           
private  java.util.List persistentTools
           
private static boolean refreshToolsPerRequest
          Should we refresh the application tools on a per request basis.
private static java.lang.String REQUEST_TOOL
           
private  java.util.List requestTools
           
private static java.lang.String resourcesDirectory
          Directory where application tool resources are stored.
private static java.lang.String SESSION_TOOL
           
private  java.util.List sessionTools
           
private static java.lang.String TOOL_RESOURCES_DIR
          Property tag for application tool resources directory
private static java.lang.String TOOL_RESOURCES_DIR_DEFAULT
          Default value for the application tool resources directory.
private static java.lang.String TOOLS_PER_REQUEST_REFRESH
          Property tag for per request tool refreshing (for obvious reasons has no effect for per-request tools)
 
Fields inherited from class org.apache.turbine.services.BaseService
configuration, name, properties, serviceBroker
 
Fields inherited from class org.apache.turbine.services.BaseInitable
initableBroker, isInitialized
 
Fields inherited from interface org.apache.turbine.services.pull.PullService
SERVICE_NAME
 
Constructor Summary
TurbinePullService()
           
 
Method Summary
 java.lang.String getAbsolutePathToResourcesDirectory()
          Return the absolute path to the resources directory used by the application tools.
 org.apache.velocity.context.Context getGlobalContext()
          Return the Context which contains all global tools that are to be used in conjunction with the Turbine Pull Model.
 java.lang.String getResourcesDirectory()
          Return the resources directory.
private  java.util.List getTools(java.lang.String keyPrefix)
          Retrieve the tool names and classes for the tools definied in the properties file with the prefix given.
 void init()
          Called the first time the Service is used.
private  void initPull()
          Initialize the pull system
 void populateContext(org.apache.velocity.context.Context context, RunData data)
          Populate the given context with all request, session and persistent scope tools (it is assumed that the context already wraps the global context, and thus already contains the global tools).
private  void populateWithGlobalTools(org.apache.velocity.context.Context context)
          Populate the given context with the global tools
private  void populateWithRequestTools(org.apache.velocity.context.Context context, RunData data)
          Populate the given context with the request-scope tools
private  void populateWithSessionTools(java.util.List tools, org.apache.velocity.context.Context context, User user, boolean usePerm)
          Populate the given context with the session-scoped tools.
 void refreshGlobalTools()
          Refresh the global tools.
 boolean refreshToolsPerRequest()
          Should we refresh the ToolBox on a per request basis.
 void releaseTools(org.apache.velocity.context.Context context)
          Release the request-scope tool instances in the given Context back to the pool
private  void releaseTools(org.apache.velocity.context.Context context, PoolService pool, java.util.List tools)
          Release the given list of tools from the context back to the pool
 
Methods inherited from class org.apache.turbine.services.TurbineBaseService
init, init, init, shutdown
 
Methods inherited from class org.apache.turbine.services.BaseService
getConfiguration, getName, getProperties, getServiceBroker, setName, setServiceBroker
 
Methods inherited from class org.apache.turbine.services.BaseInitable
getInit, getInitableBroker, setInit, setInitableBroker
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 
Methods inherited from interface org.apache.turbine.services.Service
getConfiguration, getName, getProperties, setName, setServiceBroker
 
Methods inherited from interface org.apache.turbine.services.Initable
getInit, init, setInitableBroker, shutdown
 

Field Detail

globalContext

private org.apache.velocity.context.Context globalContext
This is the container for the global web application tools that are used in conjunction with the Turbine Pull Model. All the global tools will be placed in this Context and be made accessible inside templates via the tool name specified in the TR.props file.

globalTools

private java.util.List globalTools
The lists that store tool data (name and class) for each of the different type of tool. The Lists contain ToolData objects.

requestTools

private java.util.List requestTools

sessionTools

private java.util.List sessionTools

persistentTools

private java.util.List persistentTools

GLOBAL_TOOL

private static final java.lang.String GLOBAL_TOOL
The property tags that are used in conjunction with TurbineResources.getOrderedValues(String) to get our list of tools to instantiate (one tag for each type of tool).

REQUEST_TOOL

private static final java.lang.String REQUEST_TOOL

SESSION_TOOL

private static final java.lang.String SESSION_TOOL

PERSISTENT_TOOL

private static final java.lang.String PERSISTENT_TOOL

resourcesDirectory

private static java.lang.String resourcesDirectory
Directory where application tool resources are stored.

absolutePathToResourcesDirectory

private static java.lang.String absolutePathToResourcesDirectory
The absolute path the to resources directory used by the application tools.

TOOL_RESOURCES_DIR

private static final java.lang.String TOOL_RESOURCES_DIR
Property tag for application tool resources directory

TOOL_RESOURCES_DIR_DEFAULT

private static final java.lang.String TOOL_RESOURCES_DIR_DEFAULT
Default value for the application tool resources directory. The location for the resources directory is typically WEBAPP/resources.

TOOLS_PER_REQUEST_REFRESH

private static final java.lang.String TOOLS_PER_REQUEST_REFRESH
Property tag for per request tool refreshing (for obvious reasons has no effect for per-request tools)

refreshToolsPerRequest

private static boolean refreshToolsPerRequest
Should we refresh the application tools on a per request basis.
Constructor Detail

TurbinePullService

public TurbinePullService()
Method Detail

init

public void init()
          throws InitializationException
Called the first time the Service is used.
Specified by:
init in interface Initable
Overrides:
init in class TurbineBaseService
Following copied from interface: org.apache.turbine.services.Initable
Throws:
InitializationException, - if initialization of this class was not successful.

initPull

private void initPull()
               throws java.lang.Exception
Initialize the pull system
Throws:
Exception, - a generic exception.

getTools

private java.util.List getTools(java.lang.String keyPrefix)
Retrieve the tool names and classes for the tools definied in the properties file with the prefix given.
Parameters:
keyPrefix - a String giving the property name prefix to look for

getGlobalContext

public org.apache.velocity.context.Context getGlobalContext()
Return the Context which contains all global tools that are to be used in conjunction with the Turbine Pull Model.
Specified by:
getGlobalContext in interface PullService

populateContext

public void populateContext(org.apache.velocity.context.Context context,
                            RunData data)
Populate the given context with all request, session and persistent scope tools (it is assumed that the context already wraps the global context, and thus already contains the global tools).
Specified by:
populateContext in interface PullService
Parameters:
context - a Velocity Context to populate
data - a RunData object for request specific data

populateWithGlobalTools

private void populateWithGlobalTools(org.apache.velocity.context.Context context)
Populate the given context with the global tools
Parameters:
context - a Velocity Context to populate

populateWithRequestTools

private void populateWithRequestTools(org.apache.velocity.context.Context context,
                                      RunData data)
Populate the given context with the request-scope tools
Parameters:
context - a Velocity Context to populate
data - a RunData instance

populateWithSessionTools

private void populateWithSessionTools(java.util.List tools,
                                      org.apache.velocity.context.Context context,
                                      User user,
                                      boolean usePerm)
Populate the given context with the session-scoped tools.
Parameters:
tools - The list of tools with which to populate the session.
context - The context to populate.
user - The User object whose storage to retrieve the tool from.
userPerm - Whether to retrieve the tools from the permanent storage (as opposed to the temporary storage).

getAbsolutePathToResourcesDirectory

public java.lang.String getAbsolutePathToResourcesDirectory()
Return the absolute path to the resources directory used by the application tools.
Specified by:
getAbsolutePathToResourcesDirectory in interface PullService

getResourcesDirectory

public java.lang.String getResourcesDirectory()
Return the resources directory. This is relative to the web context.
Specified by:
getResourcesDirectory in interface PullService

refreshGlobalTools

public void refreshGlobalTools()
Refresh the global tools. We can only refresh those tools that adhere to ApplicationTool interface because we know those types of tools have a refresh method.
Specified by:
refreshGlobalTools in interface PullService

refreshToolsPerRequest

public boolean refreshToolsPerRequest()
Should we refresh the ToolBox on a per request basis.
Specified by:
refreshToolsPerRequest in interface PullService

releaseTools

public void releaseTools(org.apache.velocity.context.Context context)
Release the request-scope tool instances in the given Context back to the pool
Specified by:
releaseTools in interface PullService
Parameters:
context - the Velocity Context to release tools from

releaseTools

private void releaseTools(org.apache.velocity.context.Context context,
                          PoolService pool,
                          java.util.List tools)
Release the given list of tools from the context back to the pool
Parameters:
context - the Context containing the tools
pool - an instance of the PoolService
tools - a List of ToolData objects


Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.