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  ;
22  
23  import javax.servlet.ServletContext  ;
24  import javax.servlet.ServletRequest  ;
25  import javax.servlet.ServletResponse  ;
26  import javax.servlet.http.HttpServletRequest  ;
27  import javax.servlet.http.HttpServletResponse  ;
28  import javax.servlet.http.HttpSession  ;
29  import javax.sql.DataSource  ;
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   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   request,
155         ServletResponse   response)
156         throws Exception   {
157 
158         try {
159             return execute(
160                 mapping,
161                 form,
162                 (HttpServletRequest  ) request,
163                 (HttpServletResponse  ) response);
164 
165         } catch (ClassCastException   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   request,
193         HttpServletResponse   response)
194         throws Exception   {
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   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   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   generateToken(HttpServletRequest   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   getDataSource(HttpServletRequest   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   getDataSource(HttpServletRequest   request, String   key) {
317 
318         // Identify the current module
319         ServletContext   context = getServlet().getServletContext();
320         ModuleConfig moduleConfig =
321             ModuleUtils.getInstance().getModuleConfig(request, context);
322 
323         return (DataSource  ) 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   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   getLocale(HttpServletRequest   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   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   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   request,
402         String   key) {
403 
404         // Identify the current module
405         ServletContext   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   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   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   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   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   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   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   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   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   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   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   request, Locale   locale) {
638 
639         HttpSession   session = request.getSession();
640         if (locale == null) {
641             locale = Locale.getDefault();
642         }
643         session.setAttribute(Globals.LOCALE_KEY, locale);
644 
645     }
646 
647 }
648
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags