Add support for @webfilter, @weblistener, @WebServlet

This commit adds a new annotation, @ServletComponentScan, that can be
used to enable scanning for @webfilter, @weblistener, and @WebServlet
annotated classes. Registration beans will be automatically created for
any classes that are found, with the configuration derived from the
annotation.

Author: wilkinsona

spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -348,15 +348,23 @@ Spring Boot. The definitive list comes from searching the source code for
 
 
 
-[[howto-add-a-servlet-filter-or-servletcontextlistener]]
-=== Add a Servlet, Filter or ServletContextListener to an application
-`Servlet`, `Filter`, `ServletContextListener` and the other listeners supported by the
-Servlet spec can be added to your application as `@Bean` definitions. Be very careful that
-they don't cause eager initialization of too many other beans because they have to be
-installed in the container very early in the application lifecycle (e.g. it's not a good
-idea to have them depend on your `DataSource` or JPA configuration). You can work around
-restrictions like that by initializing them lazily when first used instead of on
-initialization.
+[[howto-add-a-servlet-filter-or-listener]]
+=== Add a Servlet, Filter or Listener to an application
+There are two ways to add `Servlet`, `Filter`, `ServletContextListener` and the other
+listeners supported by the Servlet spec to your application. You can either provide
+Spring beans for them, or enable scanning for Servlet components.
+
+
+
+[[howto-add-a-servlet-filter-or-listener-as-spring-bean]]
+==== Add a Servlet, Filter or Listener using a Spring bean
+To add a `Servlet`, `Filter`, or Servlet `*Listener` provide a `@Bean` definition for it.
+This can be very useful when you want to inject configuration or dependencies. However,
+you must be very careful that they don't cause eager initialization of too many other
+beans because they have to be installed in the container very early in the application
+lifecycle (e.g. it's not a good idea to have them depend on your `DataSource` or JPA
+configuration). You can work around restrictions like that by initializing them lazily
+when first used instead of on initialization.
 
 In the case of `Filters` and `Servlets` you can also add mappings and init parameters by
 adding a `FilterRegistrationBean` or `ServletRegistrationBean` instead of or as well as
@@ -365,7 +373,7 @@ the underlying component.
 
 
 [[howto-disable-registration-of-a-servlet-or-filter]]
-=== Disable registration of a Servlet or Filter
+===== Disable registration of a Servlet or Filter
 As <<howto-add-a-servlet-filter-or-servletcontextlistener,described above>> any `Servlet`
 or `Filter` beans will be registered with the servlet container automatically. To disable
 registration of a particular `Filter` or `Servlet` bean create a registration bean for it
@@ -382,6 +390,15 @@ and mark it as disabled. For example:
 ----
 
 
+[[howto-add-a-servlet-filter-or-listener-using-scanning]]
+==== Add Servlets, Filters, and Listeners using classpath scanning
+`@WebServlet`, `@WebFilter`, and `@WebListener` annotated classes can be automatically
+registered with an embedded servlet container by annotating a `@Configuration` class
+with `@ServletComponentScan` and specifying the package(s) containing the components
+that you want to register. By default, `@ServletComponentScan` will scan from the package
+of the annotated class.
+
+
 
 [[howto-change-the-http-port]]
 === Change the HTTP port
@@ -1215,7 +1232,7 @@ using the "logging.config" property.
 [[howto-configure-logback-for-loggin]]
 === Configure Logback for logging
 If you put a `logback.xml` in the root of your classpath it will be picked up from
-there 
+there
 (or `logback-spring.xml` to take advantage of the templating features provided by Boot). Spring Boot provides a default base configuration that you can include if you just
 want to set levels, e.g.
 

spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -1585,12 +1585,18 @@ instance. By default the embedded server will listen for HTTP requests on port `
 
 
 
-[[boot-features-embedded-container-servlets-and-filters]]
-==== Servlets and Filters
+[[boot-features-embedded-container-servlets-filters-listeners]]
+==== Servlets, Filters, and listeners
 When using an embedded servlet container you can register Servlets, Filters and all the
-listeners from the Servlet spec (e.g. `HttpSessionListener`) directly as
-Spring beans. This can be particularly convenient if you want to refer to a value from
-your `application.properties` during configuration.
+listeners from the Servlet spec (e.g. `HttpSessionListener`) either by using Spring beans
+or by scanning for Servlet components.
+
+
+[[boot-features-embedded-container-servlets-filters-listeners-beans]]
+===== Registering Servlets, Filters, and listeners as Spring beans
+Any `Servlet`, `Filter` or Servlet `*Listener` instance that is a Spring bean will be
+registered with the embedded container. This can be particularly convenient if you want to
+refer to a value from your `application.properties` during configuration.
 
 By default, if the context contains only a single Servlet it will be mapped to `/`. In the
 case of multiple Servlet beans the bean name will be used as a path prefix. Filters will
@@ -1603,6 +1609,16 @@ the `ServletContextInitializer` interface.
 
 
 
+[[boot-features-embedded-container-servlets-filters-listeners-scanning]]
+===== Scanning for Servlets, Filters, and listeners
+When using an embedded container, automatic registration of `@WebServlet`, `@WebFilter`,
+and `@WebListener` annotated classes can be enabled using `@ServletComponentScan`.
+
+TIP: `@ServletComponentScan` will have no effect in a standalone container, where the
+container's built-in discovery mechanisms will be used instead.
+
+
+
 [[boot-features-embedded-container-application-context]]
 ==== The EmbeddedWebApplicationContext
 Under the hood Spring Boot uses a new type of `ApplicationContext` for embedded servlet

spring-boot/src/main/java/org/springframework/boot/web/servlet/ServletComponentHandler.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2012-2015 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.boot.web.servlet;
+
+import java.lang.annotation.Annotation;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.context.annotation.ScannedGenericBeanDefinition;
+import org.springframework.core.annotation.AnnotationAttributes;
+import org.springframework.core.type.filter.AnnotationTypeFilter;
+import org.springframework.core.type.filter.TypeFilter;
+
+/**
+ * Abstract base class for handlers of Servlet components discovered via classpath
+ * scanning.
+ *
+ * @author Andy Wilkinson
+ */
+abstract class ServletComponentHandler {
+
+	private final Class<? extends Annotation> annotationType;
+
+	private final TypeFilter typeFilter;
+
+	protected ServletComponentHandler(Class<? extends Annotation> annotationType) {
+		this.typeFilter = new AnnotationTypeFilter(annotationType);
+		this.annotationType = annotationType;
+	}
+
+	TypeFilter getTypeFilter() {
+		return this.typeFilter;
+	}
+
+	protected String[] extractUrlPatterns(String attribute, Map<String, Object> attributes) {
+		String[] urlPatterns = (String[]) attributes.get("urlPatterns");
+		if (urlPatterns.length > 0) {
+			if (((String[]) attributes.get("value")).length > 0) {
+				throw new IllegalStateException("The urlPatterns and value attributes "
+						+ "are mututally exclusive");
+			}
+			return urlPatterns;
+		}
+		return (String[]) attributes.get("value");
+	}
+
+	protected final Map<String, String> extractInitParameters(
+			Map<String, Object> attributes) {
+		Map<String, String> initParameters = new HashMap<String, String>();
+		for (AnnotationAttributes initParam : (AnnotationAttributes[]) attributes
+				.get("initParams")) {
+			String name = (String) initParam.get("name");
+			String value = (String) initParam.get("value");
+			initParameters.put(name, value);
+		}
+		return initParameters;
+	}
+
+	void handle(ScannedGenericBeanDefinition beanDefinition,
+			BeanDefinitionRegistry registry) {
+		Map<String, Object> attributes = beanDefinition.getMetadata()
+				.getAnnotationAttributes(this.annotationType.getName());
+		if (attributes != null) {
+			doHandle(attributes, beanDefinition, registry);
+		}
+	}
+
+	protected abstract void doHandle(Map<String, Object> attributes,
+			BeanDefinition beanDefinition, BeanDefinitionRegistry registry);
+
+}

spring-boot/src/main/java/org/springframework/boot/web/servlet/ServletComponentRegisteringPostProcessor.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2012-2015 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.boot.web.servlet;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
+import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.boot.context.embedded.EmbeddedWebApplicationContext;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.ApplicationContextAware;
+import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider;
+import org.springframework.context.annotation.ScannedGenericBeanDefinition;
+
+/**
+ * {@link BeanFactoryPostProcessor} that registers beans for Servlet components found via
+ * package scanning.
+ *
+ * @see ServletComponentScan
+ * @see ServletComponentScanRegistrar
+ * @author Andy Wilkinson
+ */
+class ServletComponentRegisteringPostProcessor implements BeanFactoryPostProcessor,
+		ApplicationContextAware {
+
+	private final List<ServletComponentHandler> handlers = Arrays.asList(
+			new WebServletHandler(), new WebFilterHandler(), new WebListenerHandler());
+
+	private final Set<String> packagesToScan;
+
+	private ApplicationContext applicationContext;
+
+	public ServletComponentRegisteringPostProcessor(Set<String> packagesToScan) {
+		this.packagesToScan = packagesToScan;
+	}
+
+	@Override
+	public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory)
+			throws BeansException {
+		if (isRunningInEmbeddedContainer()) {
+			ClassPathScanningCandidateComponentProvider componentProvider = createComponentProvider();
+			for (String packageToScan : this.packagesToScan) {
+				for (BeanDefinition candidate : componentProvider
+						.findCandidateComponents(packageToScan)) {
+					if (candidate instanceof ScannedGenericBeanDefinition) {
+						for (ServletComponentHandler handler : this.handlers) {
+							handler.handle(((ScannedGenericBeanDefinition) candidate),
+									(BeanDefinitionRegistry) this.applicationContext);
+						}
+					}
+				}
+			}
+		}
+	}
+
+	private boolean isRunningInEmbeddedContainer() {
+		return this.applicationContext instanceof EmbeddedWebApplicationContext
+				&& ((EmbeddedWebApplicationContext) this.applicationContext)
+						.getServletContext() == null;
+	}
+
+	private ClassPathScanningCandidateComponentProvider createComponentProvider() {
+		ClassPathScanningCandidateComponentProvider componentProvider = new ClassPathScanningCandidateComponentProvider(
+				false);
+		for (ServletComponentHandler handler : this.handlers) {
+			componentProvider.addIncludeFilter(handler.getTypeFilter());
+		}
+		return componentProvider;
+	}
+
+	Set<String> getPackagesToScan() {
+		return Collections.unmodifiableSet(this.packagesToScan);
+	}
+
+	@Override
+	public void setApplicationContext(ApplicationContext applicationContext)
+			throws BeansException {
+		this.applicationContext = applicationContext;
+	}
+
+}

spring-boot/src/main/java/org/springframework/boot/web/servlet/ServletComponentScan.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2012-2015 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.boot.web.servlet;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import javax.servlet.annotation.WebFilter;
+import javax.servlet.annotation.WebListener;
+import javax.servlet.annotation.WebServlet;
+
+import org.springframework.context.annotation.Import;
+
+/**
+ * Enables scanning for Servlet components ({@link WebFilter filters}, {@link WebServlet
+ * servlets}, and {@link WebListener listeners}). Scanning is only performed when using an
+ * embedded Servlet container.
+ * <p>
+ * Typically, one of {@code value}, {@code basePackages}, or {@code basePackageClasses}
+ * should be specified to control the packages to be scanned for components. In their
+ * absence, scanning will be performed from the package of the class with the annotation.
+ *
+ * @author Andy Wilkinson
+ * @since 1.3.0
+ * @see WebServlet
+ * @see WebFilter
+ * @see WebListener
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Import(ServletComponentScanRegistrar.class)
+public @interface ServletComponentScan {
+
+	/**
+	 * Alias for the {@link #basePackages()} attribute. Allows for more concise annotation
+	 * declarations e.g.: {@code @ServletComponentScan("org.my.pkg")} instead of
+	 * {@code @ServletComponentScan(basePackages="org.my.pkg")}.
+	 *
+	 * @return the base packages to scan
+	 */
+	String[] value() default {};
+
+	/**
+	 * Base packages to scan for annotated servlet components. {@link #value()} is an
+	 * alias for (and mutually exclusive with) this attribute.
+	 * <p>
+	 * Use {@link #basePackageClasses()} for a type-safe alternative to String-based
+	 * package names.
+	 *
+	 * @return the base packages to scan
+	 */
+	String[] basePackages() default {};
+
+	/**
+	 * Type-safe alternative to {@link #basePackages()} for specifying the packages to
+	 * scan for annotated servlet components. The package of each class specified will be
+	 * scanned.
+	 *
+	 * @return classes from the base packages to scan
+	 */
+	Class<?>[] basePackageClasses() default {};
+}