SPR-9300.diff

diff --git a/spring-web/src/main/java/org/springframework/web/WebApplicationInitializer.java b/spring-web/src/main/java/org/springframework/web/WebApplicationInitializer.java
index 2839865..7e7c92e 100644
--- a/spring-web/src/main/java/org/springframework/web/WebApplicationInitializer.java
+++ b/spring-web/src/main/java/org/springframework/web/WebApplicationInitializer.java
@@ -85,7 +85,7 @@ import javax.servlet.ServletException;
  * are free to create and work with your Spring application contexts as necessary before
  * injecting them into the {@code DispatcherServlet}.
  *
- * <p>Most major Spring Web components has been updated to support this style of
+ * <p>Most major Spring Web components have been updated to support this style of
  * registration.  You'll find that {@code DispatcherServlet}, {@code FrameworkServlet},
  * {@code ContextLoaderListener} and {@code DelegatingFilterProxy} all now support
  * constructor arguments. Even if a component (e.g. non-Spring, other third party) has not
@@ -174,7 +174,6 @@ import javax.servlet.ServletException;
  * @see org.springframework.web.context.AbstractContextLoaderInitializer
  * @see org.springframework.web.servlet.support.AbstractDispatcherServletInitializer
  * @see org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer
- * @since 3.1
  */
 public interface WebApplicationInitializer {
 
diff --git a/spring-web/src/main/java/org/springframework/web/context/AbstractContextLoaderInitializer.java b/spring-web/src/main/java/org/springframework/web/context/AbstractContextLoaderInitializer.java
index 61399c7..54defc9 100644
--- a/spring-web/src/main/java/org/springframework/web/context/AbstractContextLoaderInitializer.java
+++ b/spring-web/src/main/java/org/springframework/web/context/AbstractContextLoaderInitializer.java
@@ -25,53 +25,53 @@ import org.apache.commons.logging.LogFactory;
 import org.springframework.web.WebApplicationInitializer;
 
 /**
- * Base class for {@link org.springframework.web.WebApplicationInitializer}
- * implementations that register a {@link ContextLoaderListener} in the servlet context.
+ * Convenient base class for {@link WebApplicationInitializer} implementations that
+ * register a {@link ContextLoaderListener} in the servlet context.
  *
- * <p>The only method to be implemented by subclasses is {@link
+ * <p>The only method required to be implemented by subclasses is {@link
  * #createRootApplicationContext()}, which gets invoked from {@link
- * #addContextLoaderListener(javax.servlet.ServletContext)}.
+ * #registerContextLoaderListener(javax.servlet.ServletContext)}.
  *
  * @author Arjen Poutsma
+ * @author Chris Beams
  * @since 3.2
  */
-public abstract class AbstractContextLoaderInitializer
-		implements WebApplicationInitializer {
+public abstract class AbstractContextLoaderInitializer implements WebApplicationInitializer {
 
 	/** Logger available to subclasses. */
 	protected final Log logger = LogFactory.getLog(getClass());
 
 	public void onStartup(ServletContext servletContext) throws ServletException {
-		addContextLoaderListener(servletContext);
+		this.registerContextLoaderListener(servletContext);
 	}
 
 	/**
-	 * Adds a {@link ContextLoaderListener} to the given servlet context. The {@code
-	 * ContextLoaderListener} is initialized with the application context returned from the
-	 * {@link #createRootApplicationContext()} template method.
-	 *
-	 * @param servletContext the servlet context to register the listener with
+	 * Register a {@link ContextLoaderListener} against the given servlet context. The
+	 * {@code ContextLoaderListener} is initialized with the application context returned
+	 * from the {@link #createRootApplicationContext()} template method.
+	 * @param servletContext the servlet context to register the listener against
 	 */
-	protected void addContextLoaderListener(ServletContext servletContext) {
-		WebApplicationContext rootAppContext = createRootApplicationContext();
+	protected void registerContextLoaderListener(ServletContext servletContext) {
+		WebApplicationContext rootAppContext = this.createRootApplicationContext();
 		if (rootAppContext != null) {
 			servletContext.addListener(new ContextLoaderListener(rootAppContext));
 		}
 		else {
-			logger.warn("No ContextLoaderListener registered, as " +
+			logger.debug("No ContextLoaderListener registered, as " +
 					"createRootApplicationContext() did not return an application context");
 		}
 	}
 
 	/**
-	 * Abstract template method that creates and returns a root application context.
-	 *
-	 * <p>The returned context is used as a <strong>root</strong> context, i.e. it is passed
-	 * on to {@link ContextLoaderListener#ContextLoaderListener(WebApplicationContext)}. As
-	 * such, it typically contains middle-tier services, data sources, etc.
-	 *
+	 * Create the "root" application context to be provided to the
+	 * {@code ContextLoaderListener}.
+	 * <p>The returned context is delegated to
+	 * {@link ContextLoaderListener#ContextLoaderListener(WebApplicationContext)} and will
+	 * be established as the parent context for any {@code DispatcherServlet} application
+	 * contexts. As such, it typically contains middle-tier services, data sources, etc.
 	 * @return the root application context, or {@code null} if a root context is not
-	 *         desired
+	 * desired
+	 * @see org.springframework.web.servlet.support.AbstractDispatcherServletInitializer
 	 */
 	protected abstract WebApplicationContext createRootApplicationContext();
 
diff --git a/spring-web/src/test/java/org/springframework/web/context/ContextLoaderInitializerTests.java b/spring-web/src/test/java/org/springframework/web/context/ContextLoaderInitializerTests.java
index 35dc285..998df40 100644
--- a/spring-web/src/test/java/org/springframework/web/context/ContextLoaderInitializerTests.java
+++ b/spring-web/src/test/java/org/springframework/web/context/ContextLoaderInitializerTests.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2005-2012 the original author or authors.
+ * Copyright 2002-2012 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.
@@ -17,10 +17,10 @@
 package org.springframework.web.context;
 
 import java.util.EventListener;
+
 import javax.servlet.ServletContextEvent;
 import javax.servlet.ServletException;
 
-import static org.junit.Assert.assertTrue;
 import org.junit.Before;
 import org.junit.Test;
 
@@ -28,6 +28,8 @@ import org.springframework.mock.web.MockServletContext;
 import org.springframework.web.context.support.StaticWebApplicationContext;
 import org.springframework.web.context.support.WebApplicationContextUtils;
 
+import static org.junit.Assert.*;
+
 /**
  * Test case for {@link AbstractContextLoaderInitializer}.
  *
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractAnnotationConfigDispatcherServletInitializer.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractAnnotationConfigDispatcherServletInitializer.java
index 295546d..70bdd82 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractAnnotationConfigDispatcherServletInitializer.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractAnnotationConfigDispatcherServletInitializer.java
@@ -23,24 +23,32 @@ import org.springframework.web.context.support.AnnotationConfigWebApplicationCon
 
 /**
  * Base class for {@link org.springframework.web.WebApplicationInitializer
- * WebApplicationInitializer} implementations that register one or more {@link
- * org.springframework.web.servlet.DispatcherServlet DispatcherServlet}s in the servlet
- * context based on annotated classes, e.g. {@link org.springframework.context.annotation.Configuration
- * &#064Configuration} classes.
+ * WebApplicationInitializer} implementations that register a {@link
+ * org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
+ * configured with annotated classes, e.g. Spring's {@link
+ * org.springframework.context.annotation.Configuration @Configuration} classes.
  *
  * <p>Concrete implementations are required to implement {@link #getRootConfigClasses()},
  * {@link #getServletConfigClasses()}, as well as {@link #getServletMappings()}. Further
- * template and customization methods are provided by {@link AbstractDispatcherServletInitializer}.
+ * template and customization methods are provided by {@link
+ * AbstractDispatcherServletInitializer}.
  *
  * @author Arjen Poutsma
+ * @author Chris Beams
  * @since 3.2
  */
 public abstract class AbstractAnnotationConfigDispatcherServletInitializer
 		extends AbstractDispatcherServletInitializer {
 
+	/**
+	 * {@inheritDoc}
+	 * <p>This implementation creates an {@link AnnotationConfigWebApplicationContext},
+	 * providing it the annotated classes returned by {@link #getRootConfigClasses()}.
+	 * Returns {@code null} if {@link #getRootConfigClasses()} returns {@code null}.
+	 */
 	@Override
 	protected WebApplicationContext createRootApplicationContext() {
-		Class<?>[] rootConfigClasses = getRootConfigClasses();
+		Class<?>[] rootConfigClasses = this.getRootConfigClasses();
 		if (!ObjectUtils.isEmpty(rootConfigClasses)) {
 			AnnotationConfigWebApplicationContext rootAppContext =
 					new AnnotationConfigWebApplicationContext();
@@ -52,32 +60,41 @@ public abstract class AbstractAnnotationConfigDispatcherServletInitializer
 		}
 	}
 
+	/**
+	 * {@inheritDoc}
+	 * <p>This implementation creates an {@link AnnotationConfigWebApplicationContext},
+	 * providing it the annotated classes returned by {@link #getServletConfigClasses()}.
+	 * @throws IllegalArgumentException if {@link #getServletConfigClasses()} returns
+	 * empty or {@code null}
+	 */
 	@Override
 	protected WebApplicationContext createServletApplicationContext() {
 		AnnotationConfigWebApplicationContext servletAppContext =
 				new AnnotationConfigWebApplicationContext();
-		Class<?>[] servletConfigClasses = getServletConfigClasses();
+		Class<?>[] servletConfigClasses = this.getServletConfigClasses();
 		Assert.notEmpty(servletConfigClasses,
-				"getServletConfigClasses did not return" + "any configuration classes");
+				"getServletConfigClasses() did not return any configuration classes");
 
 		servletAppContext.register(servletConfigClasses);
 		return servletAppContext;
 	}
 
 	/**
-	 * Abstract template method that returns {@link org.springframework.context.annotation.Configuration
-	 * &#064Configuration} classes for the root application context.
-	 *
-	 * @return the configuration classes for the root application context, or {@code null} if
-	 *         a root context is not desired
+	 * Specify {@link org.springframework.context.annotation.Configuration @Configuration}
+	 * and/or {@link org.springframework.stereotype.Component @Component} classes to be
+	 * provided to the {@linkplain #createRootApplicationContext() root application context}.
+	 * @return the configuration classes for the root application context, or {@code null}
+	 * if creation and registration of a root context is not desired
 	 */
 	protected abstract Class<?>[] getRootConfigClasses();
 
 	/**
-	 * Abstract template method that returns {@link org.springframework.context.annotation.Configuration
-	 * &#064Configuration} classes for the servlet application context.
-	 *
-	 * @return the configuration classes for the servlet application context
+	 * Specify {@link org.springframework.context.annotation.Configuration @Configuration}
+	 * and/or {@link org.springframework.stereotype.Component @Component} classes to be
+	 * provided to the {@linkplain #createServletApplicationContext() dispatcher servlet
+	 * application context}.
+	 * @return the configuration classes for the dispatcher servlet application context
+	 * (may not be empty or {@code null}).
 	 */
 	protected abstract Class<?>[] getServletConfigClasses();
 
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractDispatcherServletInitializer.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractDispatcherServletInitializer.java
index 6726c4d..5f661d5 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractDispatcherServletInitializer.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/support/AbstractDispatcherServletInitializer.java
@@ -32,50 +32,51 @@ import org.springframework.web.servlet.DispatcherServlet;
  *
  * <p>Concrete implementations are required to implement {@link
  * #createServletApplicationContext()}, as well as {@link #getServletMappings()}, both of
- * which gets invoked from {@link #addDispatcherServlet}. Further
- * customization can be achieved by overriding {@link #customizeRegistration(ServletRegistration.Dynamic)}.
+ * which gets invoked from {@link #registerDispatcherServlet(ServletContext)}. Further
+ * customization can be achieved by overriding
+ * {@link #customizeRegistration(ServletRegistration.Dynamic)}.
  *
  * <p>Because this class extends from {@link AbstractContextLoaderInitializer}, concrete
  * implementations are also required to implement {@link #createRootApplicationContext()}
- * to set up a <strong>root</strong> or <strong>parent</strong> application context. If a
- * root context is not desired, implementations can simply return {@code null} in the
+ * to set up a parent "<strong>root</strong>" application context. If a root context is
+ * not desired, implementations can simply return {@code null} in the
  * {@code createRootApplicationContext()} implementation.
  *
  * @author Arjen Poutsma
+ * @author Chris Beams
  * @since 3.2
  */
 public abstract class AbstractDispatcherServletInitializer
 		extends AbstractContextLoaderInitializer {
 
-	/** The default servlet name. Can be changed by overriding {@link #getServletName}. */
+	/**
+	 * The default servlet name. Can be customized by overriding {@link #getServletName}.
+	 */
 	public static final String DEFAULT_SERVLET_NAME = "dispatcher";
 
 	@Override
 	public void onStartup(ServletContext servletContext) throws ServletException {
 		super.onStartup(servletContext);
 
-		addDispatcherServlet(servletContext);
+		this.registerDispatcherServlet(servletContext);
 	}
 
 	/**
-	 * Adds a {@link DispatcherServlet} to the given servlet context.
-	 *
+	 * Register a {@link DispatcherServlet} against the given servlet context.
 	 * <p>This method will create a {@code DispatcherServlet} with the name returned by
-	 * {@link #getServletName()}, initializing it with the application context returned from
-	 * {@link #createServletApplicationContext()}, and mapping it to the patterns returned
-	 * from {@link #getServletMappings()}.
-	 *
+	 * {@link #getServletName()}, initializing it with the application context returned
+	 * from {@link #createServletApplicationContext()}, and mapping it to the patterns
+	 * returned from {@link #getServletMappings()}.
 	 * <p>Further customization can be achieved by overriding {@link
 	 * #customizeRegistration(ServletRegistration.Dynamic)}.
-	 *
-	 * @param servletContext the servlet context to register the listener with
+	 * @param servletContext the context to register the servlet against
 	 */
-	protected void addDispatcherServlet(ServletContext servletContext) {
-		String servletName = getServletName();
+	protected void registerDispatcherServlet(ServletContext servletContext) {
+		String servletName = this.getServletName();
 		Assert.hasLength(servletName,
-				"getServletName() should not return an empty string");
+				"getServletName() may not return empty or null");
 
-		WebApplicationContext servletAppContext = createServletApplicationContext();
+		WebApplicationContext servletAppContext = this.createServletApplicationContext();
 		Assert.notNull(servletAppContext,
 				"createServletApplicationContext() did not return an application " +
 						"context for servlet [" + servletName + "]");
@@ -84,49 +85,43 @@ public abstract class AbstractDispatcherServletInitializer
 
 		ServletRegistration.Dynamic registration =
 				servletContext.addServlet(servletName, dispatcherServlet);
-
 		registration.setLoadOnStartup(1);
 		registration.addMapping(getServletMappings());
 
-		customizeRegistration(registration);
+		this.customizeRegistration(registration);
 	}
 
 	/**
-	 * Returns the name under which the {@link DispatcherServlet} will be registered.
+	 * Return the name under which the {@link DispatcherServlet} will be registered.
 	 * Defaults to {@link #DEFAULT_SERVLET_NAME}.
-	 *
-	 * @return the servlet names
+	 * @see #registerDispatcherServlet(ServletContext)
 	 */
 	protected String getServletName() {
 		return DEFAULT_SERVLET_NAME;
 	}
 
 	/**
-	 * Abstract template method that creates and returns a servlet application context.
-	 *
-	 * <p>The returned context is used as a <strong>servlet</strong> context, i.e. it is
-	 * passed on to {@link DispatcherServlet#DispatcherServlet(WebApplicationContext)} As
-	 * such, it typically contains controllers, view resolvers, locale resolvers, and other
+	 * Create a servlet application context to be provided to the {@code DispatcherServlet}.
+	 * <p>The returned context is delegated to Spring's
+	 * {@link DispatcherServlet#DispatcherServlet(WebApplicationContext)} As such, it
+	 * typically contains controllers, view resolvers, locale resolvers, and other
 	 * web-related beans.
-	 *
-	 * @return the application context for the servlet
+	 * @see #registerDispatcherServlet(ServletContext)
 	 */
 	protected abstract WebApplicationContext createServletApplicationContext();
 
 	/**
-	 * Abstract template method that returns the mappings for the servlet with the given
-	 * name.
-	 *
-	 * @return the servlet mappings for the servlet
+	 * Specify the servlet mapping(s) for the {@code DispatcherServlet}, e.g. '/', '/app',
+	 * etc.
+	 * @see #registerDispatcherServlet(ServletContext)
 	 */
 	protected abstract String[] getServletMappings();
 
 	/**
-	 * Template method that allows for further registration customization of the servlet.
-	 *
-	 * <p>The default implementation is empty.
-	 *
-	 * @param registration the registration to be customized
+	 * Optionally perform further registration customization once
+	 * {@link #registerDispatcherServlet(ServletContext)} has completed.
+	 * @param registration the {@code DispatcherServlet} registration to be customized
+	 * @see #registerDispatcherServlet(ServletContext)
 	 */
 	protected void customizeRegistration(ServletRegistration.Dynamic registration) {
 	}
diff --git a/spring-webmvc/src/test/java/org/springframework/web/servlet/support/AnnotationConfigDispatcherServletInitializerTests.java b/spring-webmvc/src/test/java/org/springframework/web/servlet/support/AnnotationConfigDispatcherServletInitializerTests.java
index 5f4a7aa..a6cf3bd 100644
--- a/spring-webmvc/src/test/java/org/springframework/web/servlet/support/AnnotationConfigDispatcherServletInitializerTests.java
+++ b/spring-webmvc/src/test/java/org/springframework/web/servlet/support/AnnotationConfigDispatcherServletInitializerTests.java
@@ -19,11 +19,11 @@ package org.springframework.web.servlet.support;
 import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.Map;
+
 import javax.servlet.Servlet;
 import javax.servlet.ServletException;
 import javax.servlet.ServletRegistration;
 
-import static org.junit.Assert.*;
 import org.junit.Before;
 import org.junit.Test;
 
@@ -34,6 +34,8 @@ import org.springframework.web.context.WebApplicationContext;
 import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
 import org.springframework.web.servlet.DispatcherServlet;
 
+import static org.junit.Assert.*;
+
 /**
  * Test case for {@link AbstractAnnotationConfigDispatcherServletInitializer}.
  *
@@ -133,6 +135,7 @@ public class AnnotationConfigDispatcherServletInitializerTests {
 	}
 
 	@Configuration
+	@SuppressWarnings("unused")
 	private static class MyConfiguration {
 
 		public MyConfiguration() {
diff --git a/spring-webmvc/src/test/java/org/springframework/web/servlet/support/MockDynamic.java b/spring-webmvc/src/test/java/org/springframework/web/servlet/support/MockDynamic.java
index 0059dea..cb43a12 100644
--- a/spring-webmvc/src/test/java/org/springframework/web/servlet/support/MockDynamic.java
+++ b/spring-webmvc/src/test/java/org/springframework/web/servlet/support/MockDynamic.java
@@ -21,6 +21,7 @@ import java.util.Collection;
 import java.util.LinkedHashSet;
 import java.util.Map;
 import java.util.Set;
+
 import javax.servlet.MultipartConfigElement;
 import javax.servlet.ServletRegistration;
 import javax.servlet.ServletSecurityElement;
diff --git a/src/dist/changelog.txt b/src/dist/changelog.txt
index da7d11a..a8d6dc2 100644
--- a/src/dist/changelog.txt
+++ b/src/dist/changelog.txt
@@ -5,8 +5,31 @@ http://www.springsource.org
 Changes in version 3.2 M1
 -------------------------------------
 
-* fix issue with parsing invalid Content-Type or Accept headers
-
+* add Servlet 3.0 based async support
+* upgraded to AspectJ 1.6.12, JUnit 4.10, TestNG 6.5.2
+* add HttpMessageConverter and View types compatible with Jackson 2.0
+* better handling on failure to parse invalid 'Content-Type' or 'Accept' headers
+* handle a controller method's return value based on the actual returned value (vs declared type)
+* fix issue with combining identical controller and method level request mapping paths
+* fix concurrency issue in AnnotationMethodHandlerExceptionResolver
+* fix case-sensitivity issue with some containers on access to 'Content-Disposition' header
+* fix issue with encoded params in UriComponentsBuilder
+* add pretty print option to Jackson HttpMessageConverter and View types
+* translate IOException from Jackson to HttpMessageNotReadableException
+* fix issue with resolving Errors controller method argument
+* implement InitializingBean in RequestMappingHandlerMapping to detect controller methods
+* fix content negotiation issue when sorting selected media types by quality value
+* prevent further writing to the response when @ResponseStatus contains a reason
+* deprecate HttpStatus codes 419, 420, 421
+* support access to all URI vars via @PathVariable Map<String, String>
+* add "excludedExceptions" property to SimpleUrlHandlerMapping
+* add CompositeRequestCondition for use with multiple custom request mapping conditions
+* add ability to configure custom MessageCodesResolver through the MVC Java config
+* add option in MappingJacksonJsonView for setting the Content-Length header
+* decode path variables when url decoding is turned off in AbstractHandlerMapping
+* add required flag to @RequestBody annotation
+* support executor qualification with @Async#value (SPR-6847)
+* add convenient WebAppInitializer base classes (SPR-9300)
 
 Changes in version 3.1.1 (2012-02-16)
 -------------------------------------