Add convenient WebAppInitializer base classes

This commit introduces three abstract WebApplicationInitializers, to be
used in the typical setup of a Spring-based web application.

 - AbstractContextLoaderInitializer provides an abstract base class for
   registering a ContextLoaderListener.

 - AbstractDispatcherServletInitializer provides an abstract base class
   for registering a DispatcherServlet, with an optional root context.

 - AbstractAnnotationConfigDispatcherServletInitializer provides an
   abstract base class for registering a DispatcherServlet and optional
   ContextLoaderListener based on annotated (e.g. @Configuration)
   classes.

Issue: SPR-9300

spring-web/src/main/java/org/springframework/web/WebApplicationInitializer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 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.
@@ -72,6 +72,9 @@ import javax.servlet.ServletException;
  *
  * }</pre>
  *
+ * As an alternative to the above, you can also extend from {@link
+ * org.springframework.web.servlet.support.AbstractDispatcherServletInitializer}.
+ *
  * As you can see, thanks to Servlet 3.0's new {@link ServletContext#addServlet} method
  * we're actually registering an <em>instance</em> of the {@code DispatcherServlet}, and
  * this means that the {@code DispatcherServlet} can now be treated like any other object
@@ -82,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 componentry 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
@@ -131,6 +134,9 @@ import javax.servlet.ServletException;
  *
  * }</pre>
  *
+ * As an alternative to the above, you can also extend from {@link
+ * org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer}.
+ *
  * Remember that {@code WebApplicationInitializer} implementations are <em>detected
  * automatically</em> -- so you are free to package them within your application as you
  * see fit.
@@ -165,6 +171,9 @@ import javax.servlet.ServletException;
  * @author Chris Beams
  * @since 3.1
  * @see SpringServletContainerInitializer
+ * @see org.springframework.web.context.AbstractContextLoaderInitializer
+ * @see org.springframework.web.servlet.support.AbstractDispatcherServletInitializer
+ * @see org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer
  */
 public interface WebApplicationInitializer {
 

spring-web/src/main/java/org/springframework/web/context/AbstractContextLoaderInitializer.java

@@ -0,0 +1,78 @@
+/*
+ * 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.
+ * 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.context;
+
+import javax.servlet.ServletContext;
+import javax.servlet.ServletException;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+import org.springframework.web.WebApplicationInitializer;
+
+/**
+ * Convenient base class for {@link WebApplicationInitializer} implementations that
+ * register a {@link ContextLoaderListener} in the servlet context.
+ *
+ * <p>The only method required to be implemented by subclasses is {@link
+ * #createRootApplicationContext()}, which gets invoked from {@link
+ * #registerContextLoaderListener(javax.servlet.ServletContext)}.
+ *
+ * @author Arjen Poutsma
+ * @author Chris Beams
+ * @since 3.2
+ */
+public abstract class AbstractContextLoaderInitializer implements WebApplicationInitializer {
+
+	/** Logger available to subclasses. */
+	protected final Log logger = LogFactory.getLog(getClass());
+
+	public void onStartup(ServletContext servletContext) throws ServletException {
+		this.registerContextLoaderListener(servletContext);
+	}
+
+	/**
+	 * 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 registerContextLoaderListener(ServletContext servletContext) {
+		WebApplicationContext rootAppContext = this.createRootApplicationContext();
+		if (rootAppContext != null) {
+			servletContext.addListener(new ContextLoaderListener(rootAppContext));
+		}
+		else {
+			logger.debug("No ContextLoaderListener registered, as " +
+					"createRootApplicationContext() did not return an application context");
+		}
+	}
+
+	/**
+	 * 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
+	 * @see org.springframework.web.servlet.support.AbstractDispatcherServletInitializer
+	 */
+	protected abstract WebApplicationContext createRootApplicationContext();
+
+}