1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 package org.apache.struts.chain.contexts;
19
20 import org.apache.commons.chain.Context;
21 import org.apache.struts.action.Action;
22 import org.apache.struts.action.ActionForm;
23 import org.apache.struts.action.ActionMessages;
24 import org.apache.struts.config.ActionConfig;
25 import org.apache.struts.config.ForwardConfig;
26 import org.apache.struts.config.ModuleConfig;
27 import org.apache.struts.util.MessageResources;
28
29 import java.util.Locale;
30 import java.util.Map;
31
32 /***
33 * <p>An ActionContext represents a view of a commons-chain
34 * <code>Context</code> which encapsulates access to request and
35 * session-scoped resources and services</p>
36 */
37 public interface ActionContext extends Context {
38 public static final String APPLICATION_SCOPE = "application";
39 public static final String SESSION_SCOPE = "session";
40 public static final String REQUEST_SCOPE = "request";
41
42
43
44
45
46 /***
47 * Signal to the instance that it will not be used any more, so that any
48 * resources which should be cleaned up can be cleaned up.
49 */
50 void release();
51
52 /***
53 * <p>Return a <code>Map</code> of Application scoped values.</p>
54 *
55 * <p>This is implemented in analogy with the Application scope in the
56 * Servlet API, but it seems reasonable to expect that any Struts
57 * implementation will have an equivalent concept.</p>
58 *
59 * <p>The ultimate meaning of "application scope" is an implementation
60 * detail left unspecified by Struts.</p>
61 *
62 * @return A Map of "application scope" attributes.
63 */
64 Map getApplicationScope();
65
66 /***
67 * <p>Return a <code>Map</code> of Session scoped values. A session is
68 * understood as a sequence of requests made by the same user.</p>
69 *
70 * <p>This is implemented in analogy with the Session scope in the Servlet
71 * API, but it seems reasonable to expect that any Struts implementation
72 * will have an equivalent concept.</p>
73 *
74 * <p>The ultimate meaning of "session scope" is an implementation detail
75 * left unspecified by Struts.</p>
76 *
77 * @return A Map of "session scope" attributes.
78 */
79 Map getSessionScope();
80
81 /***
82 * <p>Return a <code>Map</code> of request scoped values. A request is
83 * understood as the fundamental motivation for any particular instance of
84 * an <code>ActionContext</code>.</p>
85 *
86 * <p>This is implemented in analogy with the Request Context in the
87 * Servlet API, but it seems reasonable to expect that any Struts
88 * implementation will have an equivalent concept.</p>
89 *
90 * <p>The ultimate meaning of "request scope" is an implementation detail
91 * left unspecified by Struts.</p>
92 *
93 * @return a Map of "request scope" attributes.
94 */
95 Map getRequestScope();
96
97 /***
98 * Return the Map representing the scope identified by
99 * <code>scopeName</code>. Implementations should support at minimum the
100 * names associated with the constants <code>APPLICATION_SCOPE</code>,
101 * <code>SESSION_SCOPE</code>, and <code>REQUEST_SCOPE</code>, but are
102 * permitted to support others as well.
103 *
104 * @param scopeName A token identifying a scope, including but not limited
105 * to <code>APPLICATION_SCOPE</code>, <code>SESSION_SCOPE</code>,
106 * <code>REQUEST_SCOPE</code>.
107 * @return A Map of attributes for the specified scope.
108 */
109 Map getScope(String scopeName);
110
111 /***
112 * <p>Return a <code>Map</code> of parameters submitted by the user as
113 * part of this request. The keys to this map will be request parameter
114 * names (of type <code>String</code>), and the values will be
115 * <code>String[]</code>.</p>
116 *
117 * <p>This is implemented in analogy with the Request parameters of the
118 * Servlet API, but it seems reasonable to expect that any Struts
119 * implementation will have an equivalent concept.</p>
120 *
121 * @return A map of the request parameter attributes
122 */
123 Map getParameterMap();
124
125
126
127
128
129 /***
130 * <p> Set the action which has been identified to be executed as part of
131 * processing this request. </p>
132 *
133 * @param action
134 */
135 void setAction(Action action);
136
137 /***
138 * <p> Get the action which has been identified to be executed as part of
139 * processing this request. </p>
140 *
141 * @return The action to be executed with this request
142 */
143 Action getAction();
144
145 /***
146 * <p> Set the ActionForm instance which will carry any data submitted as
147 * part of this request. </p>
148 *
149 * @param form The ActionForm instance to use with this request
150 */
151 void setActionForm(ActionForm form);
152
153 /***
154 * <p> Get the ActionForm instance which will carry any data submitted as
155 * part of this request. </p>
156 *
157 * @return The ActionForm being used with this request
158 */
159 ActionForm getActionForm();
160
161 /***
162 * <p> Set the ActionConfig class contains the details for processing this
163 * request. </p>
164 *
165 * @param config The ActionConfig class to use with this request
166 */
167 void setActionConfig(ActionConfig config);
168
169 /***
170 * <p> Get the ActionConfig which contains the details for processing this
171 * request.
172 *
173 * @return The ActionConfig class being used with this request </p>
174 */
175 ActionConfig getActionConfig();
176
177 /***
178 * <p> Set the ForwardConfig which should be used as the basis of the view
179 * segment of the overall processing. This is the primary method of
180 * "communication" with the "view" sub-chain. </p>
181 *
182 * @param forward The ForwardConfig to use with this request
183 */
184 void setForwardConfig(ForwardConfig forward);
185
186 /***
187 * <p> Get the ForwardConfig which has been identified as the basis for
188 * view-processing. </p>
189 *
190 * @return The ForwardConfig being used with this request
191 */
192 ForwardConfig getForwardConfig();
193
194 /***
195 * <p> Set the include path which should be processed as part of
196 * processing this request. </p>
197 *
198 * @param include The include path to be used with this request
199 */
200 void setInclude(String include);
201
202 /***
203 * <p> Get the include path which should be processed as part of
204 * processing this request. </p>
205 *
206 * @return The include path being used with this request
207 */
208 String getInclude();
209
210 /***
211 * <p> Set the ModuleConfig which is operative for the current request.
212 * </p>
213 *
214 * @param config The ModuleConfig to be used with this request
215 */
216 void setModuleConfig(ModuleConfig config);
217
218 /***
219 * <p> Get the ModuleConfig which is operative for the current request.
220 * </p>
221 *
222 * @return The MooduleConfig being used with this request
223 */
224 ModuleConfig getModuleConfig();
225
226 /***
227 * <p> Is the ActionForm for this context valid? This method <em>does
228 * not</em> actually perform form validation. It is simply a holder
229 * property where processes which perform validation can store the results
230 * of the validation for other processes' benefit. </p>
231 *
232 * @return <code>Boolean.TRUE</code> if the form passed validation;
233 * <code>Boolean.FALSE</code> if the form failed validation; null
234 * if the form has not yet been validated
235 */
236 Boolean getFormValid();
237
238 /***
239 * <p> Store the result of the validation of the Context's ActionForm.
240 * </p>
241 *
242 * @param valid Whether the ActionForm for this request passes validation
243 */
244 void setFormValid(Boolean valid);
245
246 /***
247 * <p> Retrieve an exception which may have been caught by some code using
248 * this ActionContext, usually by an exception handler. </p>
249 *
250 * @return Any exception that may have been caught by this ActionContext
251 */
252 Exception getException();
253
254 /***
255 * <p> Store an exception in this context for use by other handling code.
256 * </p>
257 *
258 * @param e An exception to be stored for handling by another member
259 */
260 void setException(Exception e);
261
262
263
264
265
266 /***
267 * <p> Append the given messages keys to an internal cache, creating the
268 * cache if one is not already present. </p>
269 *
270 * @param messages New ActionMessages to cache
271 */
272 void addMessages(ActionMessages messages);
273
274 /***
275 * <p> Append the given errors keys to an internal cache, creating the
276 * cache if one is not already present. </p>
277 *
278 * @param errors New ActionMessages to cache as errors
279 */
280 void addErrors(ActionMessages errors);
281
282 /***
283 * <p> Retrieve error messages from an internal cache, creating an empty
284 * cache if one is not already present. </p>
285 *
286 * @return The ActionMessage cache for errors
287 */
288 ActionMessages getErrors();
289
290 /***
291 * <p> Retrieve messages from an internal cache, creating an empty cache
292 * if one is not already present. </p>
293 *
294 * @return The ActionMessage cache for errors
295 */
296 ActionMessages getMessages();
297
298 /***
299 * <p> Save the given error messages to the internal cache, clearing any
300 * previous messages in the cache. </p> <p> If the parameter is null or
301 * empty, the internal cache is removed. </p>
302 *
303 * @param errors ActionMesssages to cache as errors
304 */
305 void saveErrors(ActionMessages errors);
306
307 /***
308 * <p> Save the given messages to the internal cache, clearing any
309 * previous messages in the cache. </p> <p> If the parameter is null or
310 * empty, the internal cache is removed. </p>
311 *
312 * @param messages ActionMesssages to cache
313 */
314 void saveMessages(ActionMessages messages);
315
316 /***
317 * <p> Save the given messages to the internal cache, clearing any
318 * previous messages in the cache, but only for the specified scope. </p>
319 * <p> If the parameter is null or empty, the internal cache is removed.
320 * </p>
321 *
322 * @param scope The scope for the internal cache
323 * @param messages ActionMesssages to cache
324 */
325 void saveMessages(String scope, ActionMessages messages);
326
327
328
329
330
331 /***
332 * <p>Generate a new transaction token, to be used for enforcing a single
333 * request for a particular transaction.</p>
334 */
335 String generateToken();
336
337 /***
338 * <p> Indicate whether a transaction token for this context is valid.
339 * </p> <p> A typical implementation will place a transaction token in the
340 * session" scope Map and a matching value in the "parameter" Map. If the
341 * "session" token does not match the "parameter" attribute, or the
342 * session token is missing, then the transactional token is deemed
343 * invalid. </p>
344 */
345 boolean isTokenValid();
346
347 /***
348 * <p> Indicate whether a transaction token is stored in the "session"
349 * scope for this context, optionally clearing the token, so that the next
350 * check would return false. </p>
351 *
352 * @param reset On true, clear the transactional token
353 */
354 boolean isTokenValid(boolean reset);
355
356 /***
357 * <p> Clear any transactional token stored in the "session" scope for
358 * this context, so that the next check would return false. </p>
359 */
360 void resetToken();
361
362 /***
363 * <p> Save a new transaction token in the "session" scope for this
364 * context, creating new resources, if needed. </p>
365 */
366 void saveToken();
367
368
369
370
371
372 /***
373 * <p> Indicate if the "cancel event" state is set for for this context,
374 * </p>
375 *
376 * @see ActionContextBase.CANCEL_KEY
377 */
378 Boolean getCancelled();
379
380 /***
381 * <p> Set the "cancel event" state for this context. </p> <p>
382 *
383 * @param cancelled On true, set the cancel event state to true. On false,
384 * set the cancel event state to false.
385 * @see ActionContextBase.CANCEL_KEY
386 */
387 void setCancelled(Boolean cancelled);
388
389
390
391
392
393 /***
394 * <p>Return the default message resources for the current module.</p>
395 */
396 MessageResources getMessageResources();
397
398 /***
399 * <p>Set the default message resources for the current module.</p>
400 */
401 void setMessageResources(MessageResources resources);
402
403 /***
404 * <p>Return the specified message resources for the current module.</p>
405 *
406 * @param key The key specified in the <code><message-resources></code>
407 * element for the requested bundle
408 */
409 MessageResources getMessageResources(String key);
410
411
412
413
414
415 /***
416 * <p>Return the user's currently selected Locale.</p>
417 */
418 Locale getLocale();
419
420 /***
421 * <p>Set the user's currently selected <code>Locale</code>.</p>
422 *
423 * @param locale The user's selected Locale to be set, or null to select
424 * the server's default Locale
425 */
426 void setLocale(Locale locale);
427 }