KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > struts > action > Action


1 /*
2  * $Id: Action.java 164530 2005-04-25 03:11:07Z niallp $
3  *
4  * Copyright 2000-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
19 package org.apache.struts.action;
20
21 import java.util.Locale JavaDoc;
22
23 import javax.servlet.ServletContext JavaDoc;
24 import javax.servlet.ServletRequest JavaDoc;
25 import javax.servlet.ServletResponse JavaDoc;
26 import javax.servlet.http.HttpServletRequest JavaDoc;
27 import javax.servlet.http.HttpServletResponse JavaDoc;
28 import javax.servlet.http.HttpSession JavaDoc;
29 import javax.sql.DataSource JavaDoc;
30
31 import org.apache.struts.Globals;
32 import org.apache.struts.config.ModuleConfig;
33 import org.apache.struts.util.MessageResources;
34 import org.apache.struts.util.ModuleUtils;
35 import org.apache.struts.util.RequestUtils;
36 import org.apache.struts.util.TokenProcessor;
37
38 /**
39  * <p>An <strong>Action</strong> is an adapter between the contents of an incoming
40  * HTTP request and the corresponding business logic that should be executed to
41  * process this request. The controller (RequestProcessor) will select an
42  * appropriate Action for each request, create an instance (if necessary),
43  * and call the <code>execute</code> method.</p>
44  *
45  * <p>Actions must be programmed in a thread-safe manner, because the
46  * controller will share the same instance for multiple simultaneous
47  * requests. This means you should design with the following items in mind:
48  * </p>
49  * <ul>
50  * <li>Instance and static variables MUST NOT be used to store information
51  * related to the state of a particular request. They MAY be used to
52  * share global resources across requests for the same action.</li>
53  * <li>Access to other resources (JavaBeans, session variables, etc.) MUST
54  * be synchronized if those resources require protection. (Generally,
55  * however, resource classes should be designed to provide their own
56  * protection where necessary.</li>
57  * </ul>
58  *
59  * <p>When an <code>Action</code> instance is first created, the controller
60  * will call <code>setServlet</code> with a non-null argument to
61  * identify the servlet instance to which this Action is attached.
62  * When the servlet is to be shut down (or restarted), the
63  * <code>setServlet</code> method will be called with a <code>null</code>
64  * argument, which can be used to clean up any allocated resources in use
65  * by this Action.</p>
66  *
67  * @version $Rev: 164530 $ $Date: 2005-04-25 04:11:07 +0100 (Mon, 25 Apr 2005) $
68  */

69 public class Action {
70
71     /**
72      * <p>An instance of <code>TokenProcessor</code> to use for token functionality.</p>
73      */

74     private static TokenProcessor token = TokenProcessor.getInstance();
75     // :TODO: We can make this variable protected and remove Action's token methods
76
// or leave it private and allow the token methods to delegate their calls.
77

78
79     // ----------------------------------------------------- Instance Variables
80

81
82     /**
83      * <p>The system default Locale.</p>
84      *
85      * @deprecated Use Locale.getDefault directly. This will be removed after
86      * Struts 1.2.
87      */

88     protected static Locale JavaDoc defaultLocale = Locale.getDefault();
89     // :TODO: Remove after Struts 1.2
90

91
92     /**
93      * <p>The servlet to which we are attached.</p>
94      */

95     protected ActionServlet servlet = null;
96
97
98     // ------------------------------------------------------------- Properties
99

100
101     /**
102      * <p>Return the servlet instance to which we are attached.</p>
103      */

104     public ActionServlet getServlet() {
105
106         return (this.servlet);
107
108     }
109
110
111     /**
112      * <p>Set the servlet instance to which we are attached (if
113      * <code>servlet</code> is non-null), or release any allocated resources
114      * (if <code>servlet</code> is null).</p>
115      *
116      * @param servlet The new controller servlet, if any
117      */

118     public void setServlet(ActionServlet servlet) {
119
120         this.servlet = servlet;
121         // :FIXME: Is this suppose to release resources?
122

123
124     }
125
126
127     // --------------------------------------------------------- Public Methods
128

129
130     /**
131      * <p>Process the specified non-HTTP request, and create the
132      * corresponding non-HTTP response (or forward to another web
133      * component that will create it), with provision for handling
134      * exceptions thrown by the business logic.
135      * Return an {@link ActionForward} instance describing where and how
136      * control should be forwarded, or <code>null</code> if the response has
137      * already been completed.</p>
138      *
139      * <p>The default implementation attempts to forward to the HTTP
140      * version of this method.</p>
141      *
142      * @param mapping The ActionMapping used to select this instance
143      * @param form The optional ActionForm bean for this request (if any)
144      * @param request The non-HTTP request we are processing
145      * @param response The non-HTTP response we are creating
146      *
147      * @exception Exception if the application business logic throws
148      * an exception.
149      * @since Struts 1.1
150      */

151     public ActionForward execute(
152         ActionMapping mapping,
153         ActionForm form,
154         ServletRequest JavaDoc request,
155         ServletResponse JavaDoc response)
156         throws Exception JavaDoc {
157
158         try {
159             return execute(
160                 mapping,
161                 form,
162                 (HttpServletRequest JavaDoc) request,
163                 (HttpServletResponse JavaDoc) response);
164
165         } catch (ClassCastException JavaDoc e) {
166             return null;
167         }
168
169     }
170
171
172     /**
173      * <p>Process the specified HTTP request, and create the corresponding HTTP
174      * response (or forward to another web component that will create it),
175      * with provision for handling exceptions thrown by the business logic.
176      * Return an {@link ActionForward} instance describing where and how
177      * control should be forwarded, or <code>null</code> if the response
178      * has already been completed.</p>
179      *
180      * @param mapping The ActionMapping used to select this instance
181      * @param form The optional ActionForm bean for this request (if any)
182      * @param request The HTTP request we are processing
183      * @param response The HTTP response we are creating
184      *
185      * @exception Exception if the application business logic throws
186      * an exception
187      * @since Struts 1.1
188      */

189     public ActionForward execute(
190         ActionMapping mapping,
191         ActionForm form,
192         HttpServletRequest JavaDoc request,
193         HttpServletResponse JavaDoc response)
194         throws Exception JavaDoc {
195
196         return null;
197
198     }
199
200
201     // ---------------------------------------------------- Protected Methods
202

203
204     /**
205      * Adds the specified messages keys into the appropriate request
206      * attribute for use by the &lt;html:messages&gt; tag (if
207      * messages="true" is set), if any messages are required.
208      * Initialize the attribute if it has not already been.
209      * Otherwise, ensure that the request attribute is not set.
210      *
211      * @param request The servlet request we are processing
212      * @param messages Messages object
213      * @since Struts 1.2.1
214      */

215     protected void addMessages(
216         HttpServletRequest JavaDoc request,
217         ActionMessages messages) {
218
219         if (messages == null){
220             // bad programmer! *slap*
221
return;
222         }
223
224         // get any existing messages from the request, or make a new one
225
ActionMessages requestMessages = (ActionMessages) request.getAttribute(Globals.MESSAGE_KEY);
226         if (requestMessages == null){
227             requestMessages = new ActionMessages();
228         }
229         // add incoming messages
230
requestMessages.add(messages);
231
232         // if still empty, just wipe it out from the request
233
if (requestMessages.isEmpty()) {
234             request.removeAttribute(Globals.MESSAGE_KEY);
235             return;
236         }
237
238         // Save the messages
239
request.setAttribute(Globals.MESSAGE_KEY, requestMessages);
240     }
241
242
243     /**
244      * Adds the specified errors keys into the appropriate request attribute
245      * for use by the &lt;html:errors&gt; tag, if any messages are required.
246      * Initialize the attribute if it has not already been. Otherwise, ensure
247      * that the request attribute is not set.
248      *
249      * @param request The servlet request we are processing
250      * @param errors Errors object
251      * @since Struts 1.2.1
252      */

253     protected void addErrors(
254         HttpServletRequest JavaDoc request,
255         ActionMessages errors) {
256
257         if (errors == null){
258             // bad programmer! *slap*
259
return;
260         }
261
262         // get any existing errors from the request, or make a new one
263
ActionMessages requestErrors = (ActionMessages)request.getAttribute(Globals.ERROR_KEY);
264         if (requestErrors == null){
265             requestErrors = new ActionMessages();
266         }
267         // add incoming errors
268
requestErrors.add(errors);
269
270         // if still empty, just wipe it out from the request
271
if (requestErrors.isEmpty()) {
272             request.removeAttribute(Globals.ERROR_KEY);
273             return;
274         }
275
276         // Save the errors
277
request.setAttribute(Globals.ERROR_KEY, requestErrors);
278     }
279
280
281     /**
282      * <p>Generate a new transaction token, to be used for enforcing a single
283      * request for a particular transaction.</p>
284      *
285      * @param request The request we are processing
286      */

287     protected String JavaDoc generateToken(HttpServletRequest JavaDoc request) {
288         return token.generateToken(request);
289     }
290
291
292     /**
293      * <p>Return the default data source for the current module.</p>
294      *
295      * @param request The servlet request we are processing
296      *
297      * @since Struts 1.1
298      */

299     protected DataSource JavaDoc getDataSource(HttpServletRequest JavaDoc request) {
300
301         return (getDataSource(request, Globals.DATA_SOURCE_KEY));
302
303     }
304
305
306
307     /**
308      * <p>Return the specified data source for the current module.</p>
309      *
310      * @param request The servlet request we are processing
311      * @param key The key specified in the <code>&lt;data-sources&gt;</code>
312      * element.
313      *
314      * @since Struts 1.1
315      */

316     protected DataSource JavaDoc getDataSource(HttpServletRequest JavaDoc request, String JavaDoc key) {
317
318         // Identify the current module
319
ServletContext JavaDoc context = getServlet().getServletContext();
320         ModuleConfig moduleConfig =
321             ModuleUtils.getInstance().getModuleConfig(request, context);
322
323         return (DataSource JavaDoc) context.getAttribute(key + moduleConfig.getPrefix());
324     }
325
326
327     /**
328      * Retrieves any existing errors placed in the request by previous actions. This method could be called instead
329      * of creating a <code>new ActionMessages()<code> at the beginning of an <code>Action<code>
330      * This will prevent saveErrors() from wiping out any existing Errors
331      *
332      * @return the Errors that already exist in the request, or a new ActionMessages object if empty.
333      * @param request The servlet request we are processing
334      * @since Struts 1.2.1
335      */

336     protected ActionMessages getErrors(HttpServletRequest JavaDoc request) {
337         ActionMessages errors =
338             (ActionMessages) request.getAttribute(Globals.ERROR_KEY);
339         if (errors == null) {
340             errors = new ActionMessages();
341         }
342         return errors;
343     }
344
345
346     /**
347      * <p>Return the user's currently selected Locale.</p>
348      *
349      * @param request The request we are processing
350      */

351     protected Locale JavaDoc getLocale(HttpServletRequest JavaDoc request) {
352
353         return RequestUtils.getUserLocale(request, null);
354
355     }
356
357
358     /**
359      * Retrieves any existing messages placed in the request by previous actions. This method could be called instead
360      * of creating a <code>new ActionMessages()<code> at the beginning of an <code>Action<code>
361      * This will prevent saveMessages() from wiping out any existing Messages
362      *
363      * @return the Messages that already exist in the request, or a new ActionMessages object if empty.
364      * @param request The servlet request we are processing
365      * @since Struts 1.2.1
366      */

367     protected ActionMessages getMessages(HttpServletRequest JavaDoc request) {
368         ActionMessages messages =
369             (ActionMessages) request.getAttribute(Globals.MESSAGE_KEY);
370         if (messages == null) {
371             messages = new ActionMessages();
372         }
373         return messages;
374     }
375
376
377     /**
378      * <p>Return the default message resources for the current module.</p>
379      *
380      * @param request The servlet request we are processing
381      * @since Struts 1.1
382      */

383     protected MessageResources getResources(HttpServletRequest JavaDoc request) {
384
385         return ((MessageResources) request.getAttribute(Globals.MESSAGES_KEY));
386
387     }
388
389
390     /**
391      * <p>Return the specified message resources for the current module.</p>
392      *
393      * @param request The servlet request we are processing
394      * @param key The key specified in the
395      * <code>&lt;message-resources&gt;</code> element for the
396      * requested bundle
397      *
398      * @since Struts 1.1
399      */

400     protected MessageResources getResources(
401         HttpServletRequest JavaDoc request,
402         String JavaDoc key) {
403
404         // Identify the current module
405
ServletContext JavaDoc context = getServlet().getServletContext();
406         ModuleConfig moduleConfig =
407             ModuleUtils.getInstance().getModuleConfig(request, context);
408
409         // Return the requested message resources instance
410
return (MessageResources) context.getAttribute(
411             key + moduleConfig.getPrefix());
412
413     }
414
415
416     /**
417      * <p>Returns <code>true</code> if the current form's cancel button was
418      * pressed. This method will check if the <code>Globals.CANCEL_KEY</code>
419      * request attribute has been set, which normally occurs if the cancel
420      * button generated by <strong>CancelTag</strong> was pressed by the user
421      * in the current request. If <code>true</code>, validation performed
422      * by an <strong>ActionForm</strong>'s <code>validate()</code> method
423      * will have been skipped by the controller servlet.</p>
424      *
425      * @param request The servlet request we are processing
426      * @see org.apache.struts.taglib.html.CancelTag
427      */

428     protected boolean isCancelled(HttpServletRequest JavaDoc request) {
429
430         return (request.getAttribute(Globals.CANCEL_KEY) != null);
431
432     }
433
434
435     /**
436      * <p>Return <code>true</code> if there is a transaction token stored in
437      * the user's current session, and the value submitted as a request
438      * parameter with this action matches it. Returns <code>false</code>
439      * under any of the following circumstances:</p>
440      * <ul>
441      * <li>No session associated with this request</li>
442      * <li>No transaction token saved in the session</li>
443      * <li>No transaction token included as a request parameter</li>
444      * <li>The included transaction token value does not match the
445      * transaction token in the user's session</li>
446      * </ul>
447      *
448      * @param request The servlet request we are processing
449      */

450     protected boolean isTokenValid(HttpServletRequest JavaDoc request) {
451
452         return token.isTokenValid(request, false);
453
454     }
455
456
457     /**
458      * <p>Return <code>true</code> if there is a transaction token stored in
459      * the user's current session, and the value submitted as a request
460      * parameter with this action matches it. Returns <code>false</code> under
461      * any of the following circumstances:</p>
462      * <ul>
463      * <li>No session associated with this request</li>
464      * <li>No transaction token saved in the session</li>
465      * <li>No transaction token included as a request parameter</li>
466      * <li>The included transaction token value does not match the
467      * transaction token in the user's session</li>
468      * </ul>
469      *
470      * @param request The servlet request we are processing
471      * @param reset Should we reset the token after checking it?
472      */

473     protected boolean isTokenValid(HttpServletRequest JavaDoc request, boolean reset) {
474
475         return token.isTokenValid(request, reset);
476
477     }
478
479
480     /**
481      * <p>Reset the saved transaction token in the user's session. This
482      * indicates that transactional token checking will not be needed
483      * on the next request that is submitted.</p>
484      *
485      * @param request The servlet request we are processing
486      */

487     protected void resetToken(HttpServletRequest JavaDoc request) {
488
489         token.resetToken(request);
490
491     }
492
493
494     /**
495      * <p>Save the specified error messages keys into the appropriate request
496      * attribute for use by the &lt;html:errors&gt; tag, if any messages
497      * are required. Otherwise, ensure that the request attribute is not
498      * created.</p>
499      *
500      * @param request The servlet request we are processing
501      * @param errors Error messages object
502      * @deprecated Use saveErrors(HttpServletRequest, ActionMessages) instead.
503      * This will be removed after Struts 1.2.
504      */

505     protected void saveErrors(HttpServletRequest JavaDoc request, ActionErrors errors) {
506
507         this.saveErrors(request,(ActionMessages)errors);
508         // :TODO: Remove after Struts 1.2.
509

510     }
511
512
513     /**
514      * <p>Save the specified error messages keys into the appropriate request
515      * attribute for use by the &lt;html:errors&gt; tag, if any messages
516      * are required. Otherwise, ensure that the request attribute is not
517      * created.</p>
518      *
519      * @param request The servlet request we are processing
520      * @param errors Error messages object
521      * @since Struts 1.2
522      */

523     protected void saveErrors(HttpServletRequest JavaDoc request, ActionMessages errors) {
524
525         // Remove any error messages attribute if none are required
526
if ((errors == null) || errors.isEmpty()) {
527             request.removeAttribute(Globals.ERROR_KEY);
528             return;
529         }
530
531         // Save the error messages we need
532
request.setAttribute(Globals.ERROR_KEY, errors);
533
534     }
535
536
537     /**
538      * <p>Save the specified messages keys into the appropriate request
539      * attribute for use by the &lt;html:messages&gt; tag (if
540      * messages="true" is set), if any messages are required. Otherwise,
541      * ensure that the request attribute is not created.</p>
542      *
543      * @param request The servlet request we are processing.
544      * @param messages The messages to save. <code>null</code> or empty
545      * messages removes any existing ActionMessages in the request.
546      *
547      * @since Struts 1.1
548      */

549     protected void saveMessages(
550         HttpServletRequest JavaDoc request,
551         ActionMessages messages) {
552
553         // Remove any messages attribute if none are required
554
if ((messages == null) || messages.isEmpty()) {
555             request.removeAttribute(Globals.MESSAGE_KEY);
556             return;
557         }
558
559         // Save the messages we need
560
request.setAttribute(Globals.MESSAGE_KEY, messages);
561     }
562
563
564     /**
565      * <p>Save the specified messages keys into the appropriate session
566      * attribute for use by the &lt;html:messages&gt; tag (if
567      * messages="true" is set), if any messages are required. Otherwise,
568      * ensure that the session attribute is not created.</p>
569      *
570      * @param session The session to save the messages in.
571      * @param messages The messages to save. <code>null</code> or empty
572      * messages removes any existing ActionMessages in the session.
573      *
574      * @since Struts 1.2
575      */

576     protected void saveMessages(
577         HttpSession JavaDoc session,
578         ActionMessages messages) {
579
580         // Remove any messages attribute if none are required
581
if ((messages == null) || messages.isEmpty()) {
582             session.removeAttribute(Globals.MESSAGE_KEY);
583             return;
584         }
585
586         // Save the messages we need
587
session.setAttribute(Globals.MESSAGE_KEY, messages);
588     }
589
590
591     /**
592      * <p>Save the specified error messages keys into the appropriate session
593      * attribute for use by the &lt;html:messages&gt; tag (if messages="false")
594      * or &lt;html:errors&gt;, if any error messages are required. Otherwise,
595      * ensure that the session attribute is empty.</p>
596      *
597      * @param session The session to save the error messages in.
598      * @param errors The error messages to save. <code>null</code> or empty
599      * messages removes any existing error ActionMessages in the session.
600      *
601      * @since Struts 1.2.7
602      */

603     protected void saveErrors(
604         HttpSession JavaDoc session,
605         ActionMessages errors) {
606
607         // Remove the error attribute if none are required
608
if ((errors == null) || errors.isEmpty()) {
609             session.removeAttribute(Globals.ERROR_KEY);
610             return;
611         }
612
613         // Save the errors we need
614
session.setAttribute(Globals.ERROR_KEY, errors);
615     }
616
617
618     /**
619      * <p>Save a new transaction token in the user's current session, creating
620      * a new session if necessary.</p>
621      *
622      * @param request The servlet request we are processing
623      */

624     protected void saveToken(HttpServletRequest JavaDoc request) {
625         token.saveToken(request);
626     }
627
628
629     /**
630      * <p>Set the user's currently selected <code>Locale</code> into their
631      * <code>HttpSession</code>.</p>
632      *
633      * @param request The request we are processing
634      * @param locale The user's selected Locale to be set, or null
635      * to select the server's default Locale
636      */

637     protected void setLocale(HttpServletRequest JavaDoc request, Locale JavaDoc locale) {
638
639         HttpSession JavaDoc session = request.getSession();
640         if (locale == null) {
641             locale = Locale.getDefault();
642         }
643         session.setAttribute(Globals.LOCALE_KEY, locale);
644
645     }
646
647 }
648
Popular Tags