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