View Javadoc

1   /*
2    * $Id: ActionContext.java 421119 2006-07-12 04:49:11Z wsmoak $
3    *
4    * Copyright 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  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      // General Application Support
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     // General Struts properties
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     // ActionMessage Processing
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     // Token Processing
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     // Cancel Processing
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     // MessageResources Processing
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>&lt;message-resources&gt;</code>
407      *            element for the requested bundle
408      */
409     MessageResources getMessageResources(String key);
410 
411     // -------------------------------
412     // Locale Processing
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 }