cancellableformcontroller.java

spring api 源代码

/*
 * Copyright 2002-2007 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.servlet.mvc;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.validation.BindException;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.util.WebUtils;

/**
 * <p>Extension of <code>SimpleFormController</code> that supports "cancellation"
 * of form processing. By default, this controller looks for a given parameter in the
 * request, identified by the <code>cancelParamKey<code>. If this parameter is present,
 * then the controller will return the configured <code>cancelView</code>, otherwise
 * processing is passed back to the superclass.</p>
 *
 * <p><b><a name="workflow">Workflow
 * (<a href="SimpleFormController.html#workflow">in addition to the superclass</a>):</b><br>
 *  <ol>
 *   <li>Call to {@link #processFormSubmission processFormSubmission} which calls
 *       {@link #isCancelRequest} to see if the incoming request is to cancel the
 *       current form entry. By default, {@link #isCancelRequest} returns <code>true</code>
 *       if the configured <code>cancelParamKey</code> exists in the request.
 *       This behavior can be overridden in subclasses.</li>
 *   <li>If {@link #isCancelRequest} returns <code>false</code>, then the controller
 *       will delegate all processing back to {@link SimpleFormController SimpleFormController},
 *       otherwise it will call the {@link #onCancel} version with all parameters.
 *       By default, that method will delegate to the {@link #onCancel} version with just
 *       the command object, which will in turn simply return the configured
 *       <code>cancelView</code>. This behavior can be overridden in subclasses.</li>
 *  </ol>
 * </p>
 *
 * <p>Thanks to Erwin Bolwidt for submitting the original prototype
 * of such a cancellable form controller!</p>
 *
 * @author Rob Harrop
 * @author Juergen Hoeller
 * @since 1.2.3
 * @see #setCancelParamKey
 * @see #setCancelView
 * @see #isCancelRequest(javax.servlet.http.HttpServletRequest)
 * @see #onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)
 */
public class CancellableFormController extends SimpleFormController {

	/**
	 * Default parameter triggering the cancel action.
	 * Can be called even with validation errors on the form.
	 */
	private static final String PARAM_CANCEL = "_cancel";


	private String cancelParamKey = PARAM_CANCEL;

	private String cancelView;


	/**
	 * Set the key of the request parameter used to identify a cancel request.
	 * Default is "_cancel".
	 * <p>The parameter is recognized both when sent as a plain parameter
	 * ("_cancel") or when triggered by an image button ("_cancel.x").
   */
	public final void setCancelParamKey(String cancelParamKey) {
		this.cancelParamKey = cancelParamKey;
	}

	/**
	 * Return the key of the request parameter used to identify a cancel request.
	 */
	public final String getCancelParamKey() {
		return this.cancelParamKey;
	}

	/**
	 * Sets the name of the cancel view.
	 */
	public final void setCancelView(String cancelView) {
		this.cancelView = cancelView;
	}

	/**
	 * Gets the name of the cancel view.
	 */
	public final String getCancelView() {
		return this.cancelView;
	}


	/**
	 * Consider an explicit cancel request as a form submission too.
	 * @see #isCancelRequest(javax.servlet.http.HttpServletRequest)
	 */
	protected boolean isFormSubmission(HttpServletRequest request) {
		return super.isFormSubmission(request) || isCancelRequest(request);
	}

	/**
	 * Suppress validation for an explicit cancel request too.
	 * @see #isCancelRequest(javax.servlet.http.HttpServletRequest)
	 */
	protected boolean suppressValidation(HttpServletRequest request, Object command) {
		return super.suppressValidation(request, command) || isCancelRequest(request);
	}

	/**
	 * This implementation first checks to see if the incoming is a cancel request,
	 * through a call to {@link #isCancelRequest}. If so, control is passed to
	 * {@link #onCancel}; otherwise, control is passed up to
	 * {@link SimpleFormController#processFormSubmission}.
	 * @see #isCancelRequest
	 * @see #onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)
	 * @see SimpleFormController#processFormSubmission
	 */
	protected ModelAndView processFormSubmission(
			HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)
			throws Exception {

		if (isCancelRequest(request)) {
			return onCancel(request, response, command);
		}
		else {
			return super.processFormSubmission(request, response, command, errors);
		}
	}

	/**
	 * Determine whether the incoming request is a request to cancel the
	 * processing of the current form.
	 * <p>By default, this method returns <code>true</code> if a parameter
	 * matching the configured <code>cancelParamKey</code> is present in
	 * the request, otherwise it returns <code>false</code>. Subclasses may
	 * override this method to provide custom logic to detect a cancel request.
	 * <p>The parameter is recognized both when sent as a plain parameter
	 * ("_cancel") or when triggered by an image button ("_cancel.x").
	 * @param request current HTTP request
	 * @see #setCancelParamKey
	 * @see #PARAM_CANCEL
	 */
	protected boolean isCancelRequest(HttpServletRequest request) {
		return WebUtils.hasSubmitParameter(request, getCancelParamKey());
	}

	/**
	 * Callback method for handling a cancel request. Called if {@link #isCancelRequest}
	 * returns <code>true</code>.
	 * <p>Default implementation delegates to <code>onCancel(Object)</code> to return
	 * the configured <code>cancelView</code>. Subclasses may override either of the two
	 * methods to build a custom {@link ModelAndView ModelAndView} that may contain model
	 * parameters used in the cancel view.
	 * <p>If you simply want to move the user to a new view and you don't want to add
	 * additional model parameters, use {@link #setCancelView(String)} rather than
	 * overriding an <code>onCancel</code> method.
	 * @param request current servlet request
	 * @param response current servlet response
	 * @param command form object with request parameters bound onto it
	 * @return the prepared model and view, or <code>null</code>
	 * @throws Exception in case of errors
	 * @see #isCancelRequest(javax.servlet.http.HttpServletRequest)
	 * @see #onCancel(Object)
	 * @see #setCancelView
	 */
	protected ModelAndView onCancel(HttpServletRequest request, HttpServletResponse response, Object command)
			throws Exception {

		return onCancel(command);
	}

	/**
	 * Simple <code>onCancel</code> version. Called by the default implementation
	 * of the <code>onCancel</code> version with all parameters.
	 * <p>Default implementation returns eturns the configured <code>cancelView</code>.
	 * Subclasses may override this method to build a custom {@link ModelAndView ModelAndView}
	 * that may contain model parameters used in the cancel view.
	 * <p>If you simply want to move the user to a new view and you don't want to add
	 * additional model parameters, use {@link #setCancelView(String)} rather than
	 * overriding an <code>onCancel</code> method.
	 * @param command form object with request parameters bound onto it
	 * @return the prepared model and view, or <code>null</code>
	 * @throws Exception in case of errors
	 * @see #onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)
	 * @see #setCancelView
	 */
	protected ModelAndView onCancel(Object command) throws Exception {
		return new ModelAndView(getCancelView());
	}

}