1 package org.apache.turbine.services.pull;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 }