KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > web > servlet > mvc > CancellableFormController


1 /*
2  * Copyright 2002-2005 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.web.servlet.mvc;
18
19 import javax.servlet.http.HttpServletRequest JavaDoc;
20 import javax.servlet.http.HttpServletResponse JavaDoc;
21
22 import org.springframework.validation.BindException;
23 import org.springframework.web.servlet.ModelAndView;
24 import org.springframework.web.util.WebUtils;
25
26 /**
27  * <p>Extension of <code>SimpleFormController</code> that supports "cancellation"
28  * of form processing. By default, this controller looks for a given parameter in the
29  * request, identified by the <code>cancelParamKey<code>. If this parameter is present,
30  * then the controller will return the configured <code>cancelView</code>, otherwise
31  * processing is passed back to the superclass.</p>
32  *
33  * <p><b><a name="workflow">Workflow
34  * (<a HREF="SimpleFormController.html#workflow">in addition to the superclass</a>):</b><br>
35  * <ol>
36  * <li>Call to {@link #processFormSubmission processFormSubmission} which calls
37  * {@link #isCancelRequest} to see if the incoming request is to cancel the
38  * current form entry. By default, {@link #isCancelRequest} returns <code>true</code>
39  * if the configured <code>cancelParamKey</code> exists in the request.
40  * This behavior can be overridden in subclasses.</li>
41  * <li>If {@link #isCancelRequest} returns <code>false</code>, then the controller
42  * will delegate all processing back to {@link SimpleFormController SimpleFormController},
43  * otherwise it will call the {@link #onCancel} version with all parameters.
44  * By default, that method will delegate to the {@link #onCancel} version with just
45  * the command object, which will in turn simply return the configured
46  * <code>cancelView</code>. This behavior can be overridden in subclasses.</li>
47  * </ol>
48  * </p>
49  *
50  * @author Rob Harrop
51  * @author Juergen Hoeller
52  * @author Erwin Bolwidt
53  * @since 1.2.3
54  * @see #setCancelParamKey
55  * @see #setCancelView
56  * @see #isCancelRequest(javax.servlet.http.HttpServletRequest)
57  * @see #onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)
58  */
59 public class CancellableFormController extends SimpleFormController {
60
61     /**
62      * Default parameter triggering the cancel action.
63      * Can be called even with validation errors on the form.
64      */
65     private static final String JavaDoc PARAM_CANCEL = "_cancel";
66
67
68     private String JavaDoc cancelParamKey = PARAM_CANCEL;
69
70     private String JavaDoc cancelView;
71
72
73     /**
74      * Set the key of the request parameter used to identify a cancel request.
75      * Default is "_cancel".
76      * <p>The parameter is recognized both when sent as a plain parameter
77      * ("_cancel") or when triggered by an image button ("_cancel.x").
78    */
79     public final void setCancelParamKey(String JavaDoc cancelParamKey) {
80         this.cancelParamKey = cancelParamKey;
81     }
82
83     /**
84      * Return the key of the request parameter used to identify a cancel request.
85      */
86     public final String JavaDoc getCancelParamKey() {
87         return cancelParamKey;
88     }
89
90     /**
91      * Sets the name of the cancel view.
92      */
93     public final void setCancelView(String JavaDoc cancelView) {
94         this.cancelView = cancelView;
95     }
96
97     /**
98      * Gets the name of the cancel view.
99      */
100     public final String JavaDoc getCancelView() {
101         return cancelView;
102     }
103
104
105     /**
106      * Consider an explicit cancel request as a form submission too.
107      * @see #isCancelRequest(javax.servlet.http.HttpServletRequest)
108      */
109     protected boolean isFormSubmission(HttpServletRequest JavaDoc request) {
110         return super.isFormSubmission(request) || isCancelRequest(request);
111     }
112
113     /**
114      * This implementation first checks to see if the incoming is a cancel request,
115      * through a call to {@link #isCancelRequest}. If so, control is passed to
116      * {@link #onCancel}; otherwise, control is passed up to
117      * {@link SimpleFormController#processFormSubmission}.
118      * @see #isCancelRequest
119      * @see #onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)
120      * @see SimpleFormController#processFormSubmission
121      */
122     protected ModelAndView processFormSubmission(
123             HttpServletRequest JavaDoc request, HttpServletResponse JavaDoc response, Object JavaDoc command, BindException errors)
124             throws Exception JavaDoc {
125
126         if (isCancelRequest(request)) {
127             return onCancel(request, response, command);
128         }
129         else {
130             return super.processFormSubmission(request, response, command, errors);
131         }
132     }
133
134     /**
135      * Determine whether the incoming request is a request to cancel the
136      * processing of the current form.
137      * <p>By default, this method returns <code>true</code> if a parameter
138      * matching the configured <code>cancelParamKey</code> is present in
139      * the request, otherwise it returns <code>false</code>. Subclasses may
140      * override this method to provide custom logic to detect a cancel request.
141      * <p>The parameter is recognized both when sent as a plain parameter
142      * ("_cancel") or when triggered by an image button ("_cancel.x").
143      * @param request current HTTP request
144      * @see #setCancelParamKey
145      * @see #PARAM_CANCEL
146      */
147     protected boolean isCancelRequest(HttpServletRequest JavaDoc request) {
148         return WebUtils.hasSubmitParameter(request, getCancelParamKey());
149     }
150
151     /**
152      * Callback method for handling a cancel request. Called if {@link #isCancelRequest}
153      * returns <code>true</code>.
154      * <p>Default implementation delegates to <code>onCancel(Object)</code> to return
155      * the configured <code>cancelView</code>. Subclasses may override either of the two
156      * methods to build a custom {@link ModelAndView ModelAndView} that may contain model
157      * parameters used in the cancel view.
158      * <p>If you simply want to move the user to a new view and you don't want to add
159      * additional model parameters, use {@link #setCancelView(String)} rather than
160      * overriding an <code>onCancel</code> method.
161      * @param request current servlet request
162      * @param response current servlet response
163      * @param command form object with request parameters bound onto it
164      * @return the prepared model and view, or <code>null</code>
165      * @throws Exception in case of errors
166      * @see #isCancelRequest(javax.servlet.http.HttpServletRequest)
167      * @see #onCancel(Object)
168      * @see #setCancelView
169      */
170     protected ModelAndView onCancel(HttpServletRequest JavaDoc request, HttpServletResponse JavaDoc response, Object JavaDoc command)
171             throws Exception JavaDoc {
172
173         return onCancel(command);
174     }
175
176     /**
177      * Simple <code>onCancel</code> version. Called by the default implementation
178      * of the <code>onCancel</code> version with all parameters.
179      * <p>Default implementation returns eturns the configured <code>cancelView</code>.
180      * Subclasses may override this method to build a custom {@link ModelAndView ModelAndView}
181      * that may contain model parameters used in the cancel view.
182      * <p>If you simply want to move the user to a new view and you don't want to add
183      * additional model parameters, use {@link #setCancelView(String)} rather than
184      * overriding an <code>onCancel</code> method.
185      * @param command form object with request parameters bound onto it
186      * @return the prepared model and view, or <code>null</code>
187      * @throws Exception in case of errors
188      * @see #onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)
189      * @see #setCancelView
190      */
191     protected ModelAndView onCancel(Object JavaDoc command) throws Exception JavaDoc {
192         return new ModelAndView(getCancelView());
193     }
194
195 }
196
Popular Tags