View Javadoc

1   package org.apache.turbine.services.pull;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import org.apache.turbine.services.Service;
20  import org.apache.turbine.util.RunData;
21  import org.apache.velocity.context.Context;
22  
23  /***
24   * The Pull Service manages the creation of application
25   * tools that are available to all templates in a
26   * Turbine application. By using the Pull Service you
27   * can avoid having to make Screens to populate a
28   * context for use in a particular template. The Pull
29   * Service creates a set of tools, as specified in
30   * the TR.props file.
31   *
32   * These tools can have global scope, request scope,
33   * authorized or session scope (i.e. stored in user temp hashmap)
34   * or persistent scope (i.e. stored in user perm hashmap)
35   *
36   * The standard way of referencing these global
37   * tools is through the toolbox handle. This handle
38   * is typically $toolbox, but can be specified in the
39   * TR.props file.
40   *
41   * So, for example, if you had a UI Manager tool
42   * which created a set of UI attributes from a
43   * properties file, and one of the properties
44   * was 'bgcolor', then you could access this
45   * UI attribute with $ui.bgcolor. The identifier
46   * that is given to the tool, in this case 'ui', can
47   * be specified as well.
48   *
49   * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
50   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
51   * @version $Id: PullService.java 264148 2005-08-29 14:21:04Z henning $
52   */
53  public interface PullService
54          extends Service
55  {
56      /*** The key under which this service is stored in TurbineServices. */
57      String SERVICE_NAME = "PullService";
58  
59      /*** Property Key for the global tools */
60      String GLOBAL_TOOL = "tool.global";
61  
62      /*** Property Key for the request tools */
63      String REQUEST_TOOL = "tool.request";
64  
65      /*** Property Key for the session tools */
66      String SESSION_TOOL = "tool.session";
67  
68      /*** Property Key for the authorized tools */
69      String AUTHORIZED_TOOL = "tool.authorized";
70  
71      /*** Property Key for the persistent tools */
72      String PERSISTENT_TOOL = "tool.persistent";
73  
74      /*** Property tag for application tool resources directory */
75      String TOOL_RESOURCES_DIR_KEY = "tools.resources.dir";
76  
77      /***
78       * Default value for the application tool resources. This is relative
79       * to the webapp root
80       */
81      String TOOL_RESOURCES_DIR_DEFAULT = "resources";
82  
83      /***
84       * Property tag for per request tool refreshing (for obvious reasons
85       * has no effect for per-request tools)
86       */
87      String TOOLS_PER_REQUEST_REFRESH_KEY = "tools.per.request.refresh";
88  
89      /*** Default value for per request tool refreshing */
90      boolean TOOLS_PER_REQUEST_REFRESH_DEFAULT = false;
91  
92      /*** prefix for key used in the session to store session scope pull tools */
93      String SESSION_TOOLS_ATTRIBUTE_PREFIX = "turbine.sessiontools.";
94  
95      /***
96       * Get the context containing global tools that will be
97       * use as part of the Turbine Pull Model.
98       *
99       * @return A Context object which contains the
100      *         Global Tool instances.
101      */
102     Context getGlobalContext();
103 
104     /***
105      * Populate the given context with all request, session, authorized
106      * and persistent scope tools (it is assumed that the context
107      * already wraps the global context, and thus already contains
108      * the global tools).
109      *
110      * @param context a Velocity Context to populate
111      * @param data a RunData object for request specific data
112      */
113     void populateContext(Context context, RunData data);
114 
115     /***
116      * Return the absolute path of the resources directory
117      * used by application tools.
118      *
119      * @return A directory path in the file system or null.
120      */
121     String getAbsolutePathToResourcesDirectory();
122 
123     /***
124      * Return the resources directory. This is relative
125      * to the webapp context.
126      *
127      * @return A directory path to the resources directory relative to the webapp root or null.
128      */
129     String getResourcesDirectory();
130 
131     /***
132      * Refresh the global tools .
133      * @deprecated No longer needed as Pull and Velocity Service are now more separate.
134      */
135     void refreshGlobalTools();
136 
137     /***
138      * Shoud we refresh the tools
139      * on each request. For development purposes.
140      *
141      * @return true if we should refresh the tools on every request.
142      * @deprecated No longer needed as Pull and Velocity Service are now more separate.
143      */
144     boolean refreshToolsPerRequest();
145 
146     /***
147      * Release tool instances from the given context to the
148      * object pool
149      *
150      * @param context a Velocity Context to release tools from
151      */
152     void releaseTools(Context context);
153 }