001: /*
002: * $Id: ActionContext.java 471754 2006-11-06 14:55:09Z husted $
003: *
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021: package org.apache.struts.chain.contexts;
022:
023: import org.apache.commons.chain.Context;
024: import org.apache.struts.action.Action;
025: import org.apache.struts.action.ActionForm;
026: import org.apache.struts.action.ActionMessages;
027: import org.apache.struts.config.ActionConfig;
028: import org.apache.struts.config.ForwardConfig;
029: import org.apache.struts.config.ModuleConfig;
030: import org.apache.struts.util.MessageResources;
031:
032: import java.util.Locale;
033: import java.util.Map;
034:
035: /**
036: * <p>An ActionContext represents a view of a commons-chain
037: * <code>Context</code> which encapsulates access to request and
038: * session-scoped resources and services</p>
039: */
040: public interface ActionContext extends Context {
041: public static final String APPLICATION_SCOPE = "application";
042: public static final String SESSION_SCOPE = "session";
043: public static final String REQUEST_SCOPE = "request";
044:
045: // -------------------------------
046: // General Application Support
047: // -------------------------------
048:
049: /**
050: * Signal to the instance that it will not be used any more, so that any
051: * resources which should be cleaned up can be cleaned up.
052: */
053: void release();
054:
055: /**
056: * <p>Return a <code>Map</code> of Application scoped values.</p>
057: *
058: * <p>This is implemented in analogy with the Application scope in the
059: * Servlet API, but it seems reasonable to expect that any Struts
060: * implementation will have an equivalent concept.</p>
061: *
062: * <p>The ultimate meaning of "application scope" is an implementation
063: * detail left unspecified by Struts.</p>
064: *
065: * @return A Map of "application scope" attributes.
066: */
067: Map getApplicationScope();
068:
069: /**
070: * <p>Return a <code>Map</code> of Session scoped values. A session is
071: * understood as a sequence of requests made by the same user.</p>
072: *
073: * <p>This is implemented in analogy with the Session scope in the Servlet
074: * API, but it seems reasonable to expect that any Struts implementation
075: * will have an equivalent concept.</p>
076: *
077: * <p>The ultimate meaning of "session scope" is an implementation detail
078: * left unspecified by Struts.</p>
079: *
080: * @return A Map of "session scope" attributes.
081: */
082: Map getSessionScope();
083:
084: /**
085: * <p>Return a <code>Map</code> of request scoped values. A request is
086: * understood as the fundamental motivation for any particular instance of
087: * an <code>ActionContext</code>.</p>
088: *
089: * <p>This is implemented in analogy with the Request Context in the
090: * Servlet API, but it seems reasonable to expect that any Struts
091: * implementation will have an equivalent concept.</p>
092: *
093: * <p>The ultimate meaning of "request scope" is an implementation detail
094: * left unspecified by Struts.</p>
095: *
096: * @return a Map of "request scope" attributes.
097: */
098: Map getRequestScope();
099:
100: /**
101: * Return the Map representing the scope identified by
102: * <code>scopeName</code>. Implementations should support at minimum the
103: * names associated with the constants <code>APPLICATION_SCOPE</code>,
104: * <code>SESSION_SCOPE</code>, and <code>REQUEST_SCOPE</code>, but are
105: * permitted to support others as well.
106: *
107: * @param scopeName A token identifying a scope, including but not limited
108: * to <code>APPLICATION_SCOPE</code>, <code>SESSION_SCOPE</code>,
109: * <code>REQUEST_SCOPE</code>.
110: * @return A Map of attributes for the specified scope.
111: */
112: Map getScope(String scopeName);
113:
114: /**
115: * <p>Return a <code>Map</code> of parameters submitted by the user as
116: * part of this request. The keys to this map will be request parameter
117: * names (of type <code>String</code>), and the values will be
118: * <code>String[]</code>.</p>
119: *
120: * <p>This is implemented in analogy with the Request parameters of the
121: * Servlet API, but it seems reasonable to expect that any Struts
122: * implementation will have an equivalent concept.</p>
123: *
124: * @return A map of the request parameter attributes
125: */
126: Map getParameterMap();
127:
128: // -------------------------------
129: // General Struts properties
130: // -------------------------------
131:
132: /**
133: * <p> Set the action which has been identified to be executed as part of
134: * processing this request. </p>
135: *
136: * @param action
137: */
138: void setAction(Action action);
139:
140: /**
141: * <p> Get the action which has been identified to be executed as part of
142: * processing this request. </p>
143: *
144: * @return The action to be executed with this request
145: */
146: Action getAction();
147:
148: /**
149: * <p> Set the ActionForm instance which will carry any data submitted as
150: * part of this request. </p>
151: *
152: * @param form The ActionForm instance to use with this request
153: */
154: void setActionForm(ActionForm form);
155:
156: /**
157: * <p> Get the ActionForm instance which will carry any data submitted as
158: * part of this request. </p>
159: *
160: * @return The ActionForm being used with this request
161: */
162: ActionForm getActionForm();
163:
164: /**
165: * <p> Set the ActionConfig class contains the details for processing this
166: * request. </p>
167: *
168: * @param config The ActionConfig class to use with this request
169: */
170: void setActionConfig(ActionConfig config);
171:
172: /**
173: * <p> Get the ActionConfig which contains the details for processing this
174: * request.
175: *
176: * @return The ActionConfig class being used with this request </p>
177: */
178: ActionConfig getActionConfig();
179:
180: /**
181: * <p> Set the ForwardConfig which should be used as the basis of the view
182: * segment of the overall processing. This is the primary method of
183: * "communication" with the "view" sub-chain. </p>
184: *
185: * @param forward The ForwardConfig to use with this request
186: */
187: void setForwardConfig(ForwardConfig forward);
188:
189: /**
190: * <p> Get the ForwardConfig which has been identified as the basis for
191: * view-processing. </p>
192: *
193: * @return The ForwardConfig being used with this request
194: */
195: ForwardConfig getForwardConfig();
196:
197: /**
198: * <p> Set the include path which should be processed as part of
199: * processing this request. </p>
200: *
201: * @param include The include path to be used with this request
202: */
203: void setInclude(String include);
204:
205: /**
206: * <p> Get the include path which should be processed as part of
207: * processing this request. </p>
208: *
209: * @return The include path being used with this request
210: */
211: String getInclude();
212:
213: /**
214: * <p> Set the ModuleConfig which is operative for the current request.
215: * </p>
216: *
217: * @param config The ModuleConfig to be used with this request
218: */
219: void setModuleConfig(ModuleConfig config);
220:
221: /**
222: * <p> Get the ModuleConfig which is operative for the current request.
223: * </p>
224: *
225: * @return The MooduleConfig being used with this request
226: */
227: ModuleConfig getModuleConfig();
228:
229: /**
230: * <p> Is the ActionForm for this context valid? This method <em>does
231: * not</em> actually perform form validation. It is simply a holder
232: * property where processes which perform validation can store the results
233: * of the validation for other processes' benefit. </p>
234: *
235: * @return <code>Boolean.TRUE</code> if the form passed validation;
236: * <code>Boolean.FALSE</code> if the form failed validation; null
237: * if the form has not yet been validated
238: */
239: Boolean getFormValid();
240:
241: /**
242: * <p> Store the result of the validation of the Context's ActionForm.
243: * </p>
244: *
245: * @param valid Whether the ActionForm for this request passes validation
246: */
247: void setFormValid(Boolean valid);
248:
249: /**
250: * <p> Retrieve an exception which may have been caught by some code using
251: * this ActionContext, usually by an exception handler. </p>
252: *
253: * @return Any exception that may have been caught by this ActionContext
254: */
255: Exception getException();
256:
257: /**
258: * <p> Store an exception in this context for use by other handling code.
259: * </p>
260: *
261: * @param e An exception to be stored for handling by another member
262: */
263: void setException(Exception e);
264:
265: // -------------------------------
266: // ActionMessage Processing
267: // -------------------------------
268:
269: /**
270: * <p> Append the given messages keys to an internal cache, creating the
271: * cache if one is not already present. </p>
272: *
273: * @param messages New ActionMessages to cache
274: */
275: void addMessages(ActionMessages messages);
276:
277: /**
278: * <p> Append the given errors keys to an internal cache, creating the
279: * cache if one is not already present. </p>
280: *
281: * @param errors New ActionMessages to cache as errors
282: */
283: void addErrors(ActionMessages errors);
284:
285: /**
286: * <p> Retrieve error messages from an internal cache, creating an empty
287: * cache if one is not already present. </p>
288: *
289: * @return The ActionMessage cache for errors
290: */
291: ActionMessages getErrors();
292:
293: /**
294: * <p> Retrieve messages from an internal cache, creating an empty cache
295: * if one is not already present. </p>
296: *
297: * @return The ActionMessage cache for errors
298: */
299: ActionMessages getMessages();
300:
301: /**
302: * <p> Save the given error messages to the internal cache, clearing any
303: * previous messages in the cache. </p> <p> If the parameter is null or
304: * empty, the internal cache is removed. </p>
305: *
306: * @param errors ActionMesssages to cache as errors
307: */
308: void saveErrors(ActionMessages errors);
309:
310: /**
311: * <p> Save the given messages to the internal cache, clearing any
312: * previous messages in the cache. </p> <p> If the parameter is null or
313: * empty, the internal cache is removed. </p>
314: *
315: * @param messages ActionMesssages to cache
316: */
317: void saveMessages(ActionMessages messages);
318:
319: /**
320: * <p> Save the given messages to the internal cache, clearing any
321: * previous messages in the cache, but only for the specified scope. </p>
322: * <p> If the parameter is null or empty, the internal cache is removed.
323: * </p>
324: *
325: * @param scope The scope for the internal cache
326: * @param messages ActionMesssages to cache
327: */
328: void saveMessages(String scope, ActionMessages messages);
329:
330: // -------------------------------
331: // Token Processing
332: // -------------------------------
333:
334: /**
335: * <p>Generate a new transaction token, to be used for enforcing a single
336: * request for a particular transaction.</p>
337: */
338: String generateToken();
339:
340: /**
341: * <p> Indicate whether a transaction token for this context is valid.
342: * </p> <p> A typical implementation will place a transaction token in the
343: * session" scope Map and a matching value in the "parameter" Map. If the
344: * "session" token does not match the "parameter" attribute, or the
345: * session token is missing, then the transactional token is deemed
346: * invalid. </p>
347: */
348: boolean isTokenValid();
349:
350: /**
351: * <p> Indicate whether a transaction token is stored in the "session"
352: * scope for this context, optionally clearing the token, so that the next
353: * check would return false. </p>
354: *
355: * @param reset On true, clear the transactional token
356: */
357: boolean isTokenValid(boolean reset);
358:
359: /**
360: * <p> Clear any transactional token stored in the "session" scope for
361: * this context, so that the next check would return false. </p>
362: */
363: void resetToken();
364:
365: /**
366: * <p> Save a new transaction token in the "session" scope for this
367: * context, creating new resources, if needed. </p>
368: */
369: void saveToken();
370:
371: // -------------------------------
372: // Cancel Processing
373: // -------------------------------
374:
375: /**
376: * <p> Indicate if the "cancel event" state is set for for this context,
377: * </p>
378: *
379: * @see ActionContextBase.CANCEL_KEY
380: */
381: Boolean getCancelled();
382:
383: /**
384: * <p> Set the "cancel event" state for this context. </p> <p>
385: *
386: * @param cancelled On true, set the cancel event state to true. On false,
387: * set the cancel event state to false.
388: * @see ActionContextBase.CANCEL_KEY
389: */
390: void setCancelled(Boolean cancelled);
391:
392: // -------------------------------
393: // MessageResources Processing
394: // -------------------------------
395:
396: /**
397: * <p>Return the default message resources for the current module.</p>
398: */
399: MessageResources getMessageResources();
400:
401: /**
402: * <p>Set the default message resources for the current module.</p>
403: */
404: void setMessageResources(MessageResources resources);
405:
406: /**
407: * <p>Return the specified message resources for the current module.</p>
408: *
409: * @param key The key specified in the <code><message-resources></code>
410: * element for the requested bundle
411: */
412: MessageResources getMessageResources(String key);
413:
414: // -------------------------------
415: // Locale Processing
416: // -------------------------------
417:
418: /**
419: * <p>Return the user's currently selected Locale.</p>
420: */
421: Locale getLocale();
422:
423: /**
424: * <p>Set the user's currently selected <code>Locale</code>.</p>
425: *
426: * @param locale The user's selected Locale to be set, or null to select
427: * the server's default Locale
428: */
429: void setLocale(Locale locale);
430: }
|