org.springframework.web.servlet.handler
Class SimpleMappingExceptionResolver

java.lang.Object
  extended by org.springframework.web.servlet.handler.SimpleMappingExceptionResolver
All Implemented Interfaces:
Ordered, HandlerExceptionResolver

public class SimpleMappingExceptionResolver
extends java.lang.Object
implements HandlerExceptionResolver, Ordered

HandlerExceptionResolver implementation that allows for mapping exception class names to view names, either for a set of given handlers or for all handlers in the DispatcherServlet.

Error views are analogous to error page JSPs, but can be used with any kind of exception including any checked one, with fine-granular mappings for specific handlers.

Since:
22.11.2003
Author:
Juergen Hoeller
See Also:
DispatcherServlet

Field Summary
static java.lang.String DEFAULT_EXCEPTION_ATTRIBUTE
          The default name of the exception attribute: "exception".
protected  org.apache.commons.logging.Log logger
          Logger available to subclasses
 
Fields inherited from interface org.springframework.core.Ordered
HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE
 
Constructor Summary
SimpleMappingExceptionResolver()
           
 
Method Summary
protected  void applyStatusCodeIfPossible(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, int statusCode)
          Apply the specified HTTP status code to the given response, if possible (that is, if not executing within an include request).
protected  java.lang.String buildLogMessage(java.lang.Exception ex, javax.servlet.http.HttpServletRequest request)
          Build a log message for the given exception, occured during processing the given request.
protected  java.lang.Integer determineStatusCode(javax.servlet.http.HttpServletRequest request, java.lang.String viewName)
          Determine the HTTP status code to apply for the given error view.
protected  java.lang.String determineViewName(java.lang.Exception ex, javax.servlet.http.HttpServletRequest request)
          Determine the view name for the given exception, searching the "exceptionMappings", using the "defaultErrorView" as fallback.
protected  ModelAndView doResolveException(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object handler, java.lang.Exception ex)
          Actually resolve the given exception that got thrown during on handler execution, returning a ModelAndView that represents a specific error page if appropriate.
protected  java.lang.String findMatchingViewName(java.util.Properties exceptionMappings, java.lang.Exception ex)
          Find a matching view name in the given exception mappings.
protected  int getDepth(java.lang.String exceptionMapping, java.lang.Exception ex)
          Return the depth to the superclass matching.
protected  ModelAndView getModelAndView(java.lang.String viewName, java.lang.Exception ex)
          Return a ModelAndView for the given view name and exception.
protected  ModelAndView getModelAndView(java.lang.String viewName, java.lang.Exception ex, javax.servlet.http.HttpServletRequest request)
          Return a ModelAndView for the given request, view name and exception.
 int getOrder()
          Return the order value of this object, with a higher value meaning greater in terms of sorting.
protected  void logException(java.lang.Exception ex, javax.servlet.http.HttpServletRequest request)
          Log the given exception at warn level, provided that warn logging has been activated through the "warnLogCategory" property.
 ModelAndView resolveException(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object handler, java.lang.Exception ex)
          Checks whether this resolver is supposed to apply (i.e.
 void setDefaultErrorView(java.lang.String defaultErrorView)
          Set the name of the default error view.
 void setDefaultStatusCode(int defaultStatusCode)
          Set the default HTTP status code that this exception resolver will apply if it resolves an error view.
 void setExceptionAttribute(java.lang.String exceptionAttribute)
          Set the name of the model attribute as which the exception should be exposed.
 void setExceptionMappings(java.util.Properties mappings)
          Set the mappings between exception class names and error view names.
 void setMappedHandlerClasses(java.lang.Class[] mappedHandlerClasses)
          Specify the set of classes that this exception resolver should apply to.
 void setMappedHandlers(java.util.Set mappedHandlers)
          Specify the set of handlers that this exception resolver should apply to.
 void setOrder(int order)
           
 void setWarnLogCategory(java.lang.String loggerName)
          Set the log category for warn logging.
protected  boolean shouldApplyTo(javax.servlet.http.HttpServletRequest request, java.lang.Object handler)
          Check whether this resolver is supposed to apply to the given handler.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_EXCEPTION_ATTRIBUTE

public static final java.lang.String DEFAULT_EXCEPTION_ATTRIBUTE
The default name of the exception attribute: "exception".

See Also:
Constant Field Values

logger

protected final org.apache.commons.logging.Log logger
Logger available to subclasses

Constructor Detail

SimpleMappingExceptionResolver

public SimpleMappingExceptionResolver()
Method Detail

setOrder

public void setOrder(int order)

getOrder

public int getOrder()
Description copied from interface: Ordered
Return the order value of this object, with a higher value meaning greater in terms of sorting.

Normally starting with 0 or 1, with Ordered.LOWEST_PRECEDENCE indicating greatest. Same order values will result in arbitrary positions for the affected objects.

Higher value can be interpreted as lower priority, consequently the first object has highest priority (somewhat analogous to Servlet "load-on-startup" values).

Note that order values below 0 are reserved for framework purposes. Application-specified values should always be 0 or greater, with only framework components (internal or third-party) supposed to use lower values.

Specified by:
getOrder in interface Ordered
Returns:
the order value
See Also:
Ordered.LOWEST_PRECEDENCE

setMappedHandlers

public void setMappedHandlers(java.util.Set mappedHandlers)
Specify the set of handlers that this exception resolver should apply to. The exception mappings and the default error view will only apply to the specified handlers.

If no handlers and handler classes are set, the exception mappings and the default error view will apply to all handlers. This means that a specified default error view will be used as fallback for all exceptions; any further HandlerExceptionResolvers in the chain will be ignored in this case.


setMappedHandlerClasses

public void setMappedHandlerClasses(java.lang.Class[] mappedHandlerClasses)
Specify the set of classes that this exception resolver should apply to. The exception mappings and the default error view will only apply to handlers of the specified type; the specified types may be interfaces and superclasses of handlers as well.

If no handlers and handler classes are set, the exception mappings and the default error view will apply to all handlers. This means that a specified default error view will be used as fallback for all exceptions; any further HandlerExceptionResolvers in the chain will be ignored in this case.


setWarnLogCategory

public void setWarnLogCategory(java.lang.String loggerName)
Set the log category for warn logging. The name will be passed to the underlying logger implementation through Commons Logging, getting interpreted as log category according to the logger's configuration.

Default is no warn logging. Specify this setting to activate warn logging into a specific category. Alternatively, override the logException(java.lang.Exception, javax.servlet.http.HttpServletRequest) method for custom logging.

See Also:
LogFactory.getLog(String), Logger.getLogger(String), Logger.getLogger(String)

setExceptionMappings

public void setExceptionMappings(java.util.Properties mappings)
Set the mappings between exception class names and error view names. The exception class name can be a substring, with no wildcard support at present. A value of "ServletException" would match javax.servlet.ServletException and subclasses, for example.

NB: Consider carefully how specific the pattern is, and whether to include package information (which isn't mandatory). For example, "Exception" will match nearly anything, and will probably hide other rules. "java.lang.Exception" would be correct if "Exception" was meant to define a rule for all checked exceptions. With more unusual exception names such as "BaseBusinessException" there's no need to use a FQN.

Follows the same matching algorithm as RuleBasedTransactionAttribute and RollbackRuleAttribute.

Parameters:
mappings - exception patterns (can also be fully qualified class names) as keys, and error view names as values
See Also:
RuleBasedTransactionAttribute, RollbackRuleAttribute

setDefaultErrorView

public void setDefaultErrorView(java.lang.String defaultErrorView)
Set the name of the default error view. This view will be returned if no specific mapping was found.

Default is none.


setDefaultStatusCode

public void setDefaultStatusCode(int defaultStatusCode)
Set the default HTTP status code that this exception resolver will apply if it resolves an error view.

Note that this error code will only get applied in case of a top-level request. It will not be set for an include request, since the HTTP status cannot be modified from within an include.

If not specified, no status code will be applied, either leaving this to the controller or view, or keeping the servlet engine's default of 200 (OK).

Parameters:
defaultStatusCode - HTTP status code value, for example 500 (SC_INTERNAL_SERVER_ERROR) or 404 (SC_NOT_FOUND)
See Also:
HttpServletResponse.SC_INTERNAL_SERVER_ERROR, HttpServletResponse.SC_NOT_FOUND

setExceptionAttribute

public void setExceptionAttribute(java.lang.String exceptionAttribute)
Set the name of the model attribute as which the exception should be exposed. Default is "exception".

This can be either set to a different attribute name or to null for not exposing an exception attribute at all.

See Also:
DEFAULT_EXCEPTION_ATTRIBUTE

resolveException

public ModelAndView resolveException(javax.servlet.http.HttpServletRequest request,
                                     javax.servlet.http.HttpServletResponse response,
                                     java.lang.Object handler,
                                     java.lang.Exception ex)
Checks whether this resolver is supposed to apply (i.e. the handler matches in case of "mappedHandlers" having been specified), then delegates to the doResolveException(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, java.lang.Exception) template method.

Specified by:
resolveException in interface HandlerExceptionResolver
Parameters:
request - current HTTP request
response - current HTTP response
handler - the executed handler, or null if none chosen at the time of the exception (for example, if multipart resolution failed)
ex - the exception that got thrown during handler execution
Returns:
a corresponding ModelAndView to forward to, or null for default processing

shouldApplyTo

protected boolean shouldApplyTo(javax.servlet.http.HttpServletRequest request,
                                java.lang.Object handler)
Check whether this resolver is supposed to apply to the given handler.

The default implementation checks against the specified mapped handlers and handler classes, if any.

Parameters:
request - current HTTP request
handler - the executed handler, or null if none chosen at the time of the exception (for example, if multipart resolution failed)
Returns:
whether this resolved should proceed with resolving the exception for the given request and handler
See Also:
setMappedHandlers(java.util.Set), setMappedHandlerClasses(java.lang.Class[])

doResolveException

protected ModelAndView doResolveException(javax.servlet.http.HttpServletRequest request,
                                          javax.servlet.http.HttpServletResponse response,
                                          java.lang.Object handler,
                                          java.lang.Exception ex)
Actually resolve the given exception that got thrown during on handler execution, returning a ModelAndView that represents a specific error page if appropriate.

May be overridden in subclasses, in order to apply specific exception checks. Note that this template method will be invoked after checking whether this resolved applies ("mappedHandlers" etc), so an implementation may simply proceed with its actual exception handling.

Parameters:
request - current HTTP request
response - current HTTP response
handler - the executed handler, or null if none chosen at the time of the exception (for example, if multipart resolution failed)
ex - the exception that got thrown during handler execution
Returns:
a corresponding ModelAndView to forward to, or null for default processing

logException

protected void logException(java.lang.Exception ex,
                            javax.servlet.http.HttpServletRequest request)
Log the given exception at warn level, provided that warn logging has been activated through the "warnLogCategory" property.

Calls buildLogMessage(java.lang.Exception, javax.servlet.http.HttpServletRequest) in order to determine the concrete message to log. Always passes the full exception to the logger.

Parameters:
ex - the exception that got thrown during handler execution
request - current HTTP request (useful for obtaining metadata)
See Also:
setWarnLogCategory(java.lang.String), buildLogMessage(java.lang.Exception, javax.servlet.http.HttpServletRequest), Log.warn(Object, Throwable)

buildLogMessage

protected java.lang.String buildLogMessage(java.lang.Exception ex,
                                           javax.servlet.http.HttpServletRequest request)
Build a log message for the given exception, occured during processing the given request.

Parameters:
ex - the exception that got thrown during handler execution
request - current HTTP request (useful for obtaining metadata)
Returns:
the log message to use

determineViewName

protected java.lang.String determineViewName(java.lang.Exception ex,
                                             javax.servlet.http.HttpServletRequest request)
Determine the view name for the given exception, searching the "exceptionMappings", using the "defaultErrorView" as fallback.

Parameters:
ex - the exception that got thrown during handler execution
request - current HTTP request (useful for obtaining metadata)
Returns:
the resolved view name, or null if none found

findMatchingViewName

protected java.lang.String findMatchingViewName(java.util.Properties exceptionMappings,
                                                java.lang.Exception ex)
Find a matching view name in the given exception mappings.

Parameters:
exceptionMappings - mappings between exception class names and error view names
ex - the exception that got thrown during handler execution
Returns:
the view name, or null if none found
See Also:
setExceptionMappings(java.util.Properties)

getDepth

protected int getDepth(java.lang.String exceptionMapping,
                       java.lang.Exception ex)
Return the depth to the superclass matching.

0 means ex matches exactly. Returns -1 if there's no match. Otherwise, returns depth. Lowest depth wins.

Follows the same algorithm as RollbackRuleAttribute.


determineStatusCode

protected java.lang.Integer determineStatusCode(javax.servlet.http.HttpServletRequest request,
                                                java.lang.String viewName)
Determine the HTTP status code to apply for the given error view.

The default implementation always returns the specified "defaultStatusCode", as a common status code for all error views. Override this in a custom subclass to determine a specific status code for the given view.

Parameters:
request - current HTTP request
viewName - the name of the error view
Returns:
the HTTP status code to use, or null for the servlet container's default (200 in case of a standard error view)
See Also:
setDefaultStatusCode(int), applyStatusCodeIfPossible(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, int)

applyStatusCodeIfPossible

protected void applyStatusCodeIfPossible(javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response,
                                         int statusCode)
Apply the specified HTTP status code to the given response, if possible (that is, if not executing within an include request).

Parameters:
request - current HTTP request
response - current HTTP response
statusCode - the status code to apply
See Also:
determineStatusCode(javax.servlet.http.HttpServletRequest, java.lang.String), setDefaultStatusCode(int), HttpServletResponse.setStatus(int)

getModelAndView

protected ModelAndView getModelAndView(java.lang.String viewName,
                                       java.lang.Exception ex,
                                       javax.servlet.http.HttpServletRequest request)
Return a ModelAndView for the given request, view name and exception.

The default implementation delegates to getModelAndView(String, Exception).

Parameters:
viewName - the name of the error view
ex - the exception that got thrown during handler execution
request - current HTTP request (useful for obtaining metadata)
Returns:
the ModelAndView instance

getModelAndView

protected ModelAndView getModelAndView(java.lang.String viewName,
                                       java.lang.Exception ex)
Return a ModelAndView for the given view name and exception.

The default implementation adds the specified exception attribute. Can be overridden in subclasses.

Parameters:
viewName - the name of the error view
ex - the exception that got thrown during handler execution
Returns:
the ModelAndView instance
See Also:
setExceptionAttribute(java.lang.String)