Backport of WebMvcConfigurationSupport javadoc revision

Includes related polishing.

Author: jhoeller

spring-test/src/main/java/org/springframework/test/web/servlet/ResultMatcher.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -50,7 +50,6 @@ public interface ResultMatcher {
 
 	/**
 	 * Assert the result of an executed request.
-	 *
 	 * @param result the result of the executed request
 	 * @throws Exception if a failure occurs
 	 */

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurationSupport.java

@@ -105,7 +105,7 @@
  * subclass and {@link Bean @Bean} to overridden {@link Bean @Bean} methods.
  * For more details see the javadoc of {@link EnableWebMvc @EnableWebMvc}.
  *
- * <p>This class registers the following {@link HandlerMapping}s:</p>
+ * <p>This class registers the following {@link HandlerMapping HandlerMappings}:</p>
  * <ul>
  * <li>{@link RequestMappingHandlerMapping}
  * ordered at 0 for mapping requests to annotated controller methods.
@@ -119,14 +119,14 @@
  * ordered at {@code Integer.MAX_VALUE} to forward requests to the default servlet.
  * </ul>
  *
- * <p>Registers these {@link HandlerAdapter}s:
+ * <p>Registers these {@link HandlerAdapter HandlerAdapters}:
  * <ul>
  * <li>{@link RequestMappingHandlerAdapter}
  * for processing requests with annotated controller methods.
  * <li>{@link HttpRequestHandlerAdapter}
- * for processing requests with {@link HttpRequestHandler}s.
+ * for processing requests with {@link HttpRequestHandler HttpRequestHandlers}.
  * <li>{@link SimpleControllerHandlerAdapter}
- * for processing requests with interface-based {@link Controller}s.
+ * for processing requests with interface-based {@link Controller Controllers}.
  * </ul>
  *
  * <p>Registers a {@link HandlerExceptionResolverComposite} with this chain of
@@ -157,7 +157,7 @@
  * <li>a {@link DefaultFormattingConversionService}
  * <li>a {@link org.springframework.validation.beanvalidation.OptionalValidatorFactoryBean}
  * if a JSR-303 implementation is available on the classpath
- * <li>a range of {@link HttpMessageConverter}s depending on the third-party
+ * <li>a range of {@link HttpMessageConverter HttpMessageConverters} depending on the third-party
  * libraries available on the classpath.
  * </ul>
  *
@@ -171,7 +171,7 @@
  */
 public class WebMvcConfigurationSupport implements ApplicationContextAware, ServletContextAware {
 
-	private static boolean romePresent =
+	private static final boolean romePresent =
 			ClassUtils.isPresent("com.rometools.rome.feed.WireFeed",
 					WebMvcConfigurationSupport.class.getClassLoader());
 
@@ -260,15 +260,20 @@ public RequestMappingHandlerMapping requestMappingHandlerMapping() {
 		mapping.setCorsConfigurations(getCorsConfigurations());
 
 		PathMatchConfigurer configurer = getPathMatchConfigurer();
-		if (configurer.isUseSuffixPatternMatch() != null) {
-			mapping.setUseSuffixPatternMatch(configurer.isUseSuffixPatternMatch());
+
+		Boolean useSuffixPatternMatch = configurer.isUseSuffixPatternMatch();
+		if (useSuffixPatternMatch != null) {
+			mapping.setUseSuffixPatternMatch(useSuffixPatternMatch);
 		}
-		if (configurer.isUseRegisteredSuffixPatternMatch() != null) {
-			mapping.setUseRegisteredSuffixPatternMatch(configurer.isUseRegisteredSuffixPatternMatch());
+		Boolean useRegisteredSuffixPatternMatch = configurer.isUseRegisteredSuffixPatternMatch();
+		if (useRegisteredSuffixPatternMatch != null) {
+			mapping.setUseRegisteredSuffixPatternMatch(useRegisteredSuffixPatternMatch);
 		}
-		if (configurer.isUseTrailingSlashMatch() != null) {
-			mapping.setUseTrailingSlashMatch(configurer.isUseTrailingSlashMatch());
+		Boolean useTrailingSlashMatch = configurer.isUseTrailingSlashMatch();
+		if (useTrailingSlashMatch != null) {
+			mapping.setUseTrailingSlashMatch(useTrailingSlashMatch);
 		}
+
 		UrlPathHelper pathHelper = configurer.getUrlPathHelper();
 		if (pathHelper != null) {
 			mapping.setUrlPathHelper(pathHelper);
@@ -292,8 +297,8 @@ protected RequestMappingHandlerMapping createRequestMappingHandlerMapping() {
 
 	/**
 	 * Provide access to the shared handler interceptors used to configure
-	 * {@link HandlerMapping} instances with. This method cannot be overridden,
-	 * use {@link #addInterceptors(InterceptorRegistry)} instead.
+	 * {@link HandlerMapping} instances with.
+	 * <p>This method cannot be overridden; use {@link #addInterceptors} instead.
 	 */
 	protected final Object[] getInterceptors() {
 		if (this.interceptors == null) {
@@ -329,15 +334,15 @@ protected PathMatchConfigurer getPathMatchConfigurer() {
 
 	/**
 	 * Override this method to configure path matching options.
-	 * @see PathMatchConfigurer
 	 * @since 4.0.3
+	 * @see PathMatchConfigurer
 	 */
 	protected void configurePathMatch(PathMatchConfigurer configurer) {
 	}
 
 	/**
 	 * Return a global {@link PathMatcher} instance for path matching
-	 * patterns in {@link HandlerMapping}s.
+	 * patterns in {@link HandlerMapping HandlerMappings}.
 	 * This instance can be configured using the {@link PathMatchConfigurer}
 	 * in {@link #configurePathMatch(PathMatchConfigurer)}.
 	 * @since 4.1
@@ -350,7 +355,7 @@ public PathMatcher mvcPathMatcher() {
 
 	/**
 	 * Return a global {@link UrlPathHelper} instance for path matching
-	 * patterns in {@link HandlerMapping}s.
+	 * patterns in {@link HandlerMapping HandlerMappings}.
 	 * This instance can be configured using the {@link PathMatchConfigurer}
 	 * in {@link #configurePathMatch(PathMatchConfigurer)}.
 	 * @since 4.1
@@ -586,9 +591,8 @@ protected void configureAsyncSupport(AsyncSupportConfigurer configurer) {
 	}
 
 	/**
-	 * Return a {@link FormattingConversionService} for use with annotated
-	 * controller methods and the {@code spring:eval} JSP tag.
-	 * Also see {@link #addFormatters} as an alternative to overriding this method.
+	 * Return a {@link FormattingConversionService} for use with annotated controllers.
+	 * <p>See {@link #addFormatters} as an alternative to overriding this method.
 	 */
 	@Bean
 	public FormattingConversionService mvcConversionService() {
@@ -598,7 +602,9 @@ public FormattingConversionService mvcConversionService() {
 	}
 
 	/**
-	 * Override this method to add custom {@link Converter}s and {@link Formatter}s.
+	 * Override this method to add custom {@link Converter} and/or {@link Formatter}
+	 * delegates to the common {@link FormattingConversionService}.
+	 * @see #mvcConversionService()
 	 */
 	protected void addFormatters(FormatterRegistry registry) {
 	}
@@ -645,9 +651,8 @@ protected Validator getValidator() {
 
 	/**
 	 * Provide access to the shared custom argument resolvers used by the
-	 * {@link RequestMappingHandlerAdapter} and the
-	 * {@link ExceptionHandlerExceptionResolver}. This method cannot be
-	 * overridden, use {@link #addArgumentResolvers(List)} instead.
+	 * {@link RequestMappingHandlerAdapter} and the {@link ExceptionHandlerExceptionResolver}.
+	 * <p>This method cannot be overridden; use {@link #addArgumentResolvers} instead.
 	 * @since 4.3
 	 */
 	protected final List<HandlerMethodArgumentResolver> getArgumentResolvers() {
@@ -659,24 +664,21 @@ protected final List<HandlerMethodArgumentResolver> getArgumentResolvers() {
 	}
 
 	/**
-	 * Add custom {@link HandlerMethodArgumentResolver}s to use in addition to
-	 * the ones registered by default.
-	 * <p>Custom argument resolvers are invoked before built-in resolvers
-	 * except for those that rely on the presence of annotations (e.g.
-	 * {@code @RequestParameter}, {@code @PathVariable}, etc.).
-	 * The latter can  be customized by configuring the
+	 * Add custom {@link HandlerMethodArgumentResolver HandlerMethodArgumentResolvers}
+	 * to use in addition to the ones registered by default.
+	 * <p>Custom argument resolvers are invoked before built-in resolvers except for
+	 * those that rely on the presence of annotations (e.g. {@code @RequestParameter},
+	 * {@code @PathVariable}, etc). The latter can be customized by configuring the
 	 * {@link RequestMappingHandlerAdapter} directly.
-	 * @param argumentResolvers the list of custom converters;
-	 * 	initially an empty list.
+	 * @param argumentResolvers the list of custom converters (initially an empty list)
 	 */
 	protected void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) {
 	}
 
 	/**
 	 * Provide access to the shared return value handlers used by the
-	 * {@link RequestMappingHandlerAdapter} and the
-	 * {@link ExceptionHandlerExceptionResolver}. This method cannot be
-	 * overridden, use {@link #addReturnValueHandlers(List)} instead.
+	 * {@link RequestMappingHandlerAdapter} and the {@link ExceptionHandlerExceptionResolver}.
+	 * <p>This method cannot be overridden; use {@link #addReturnValueHandlers} instead.
 	 * @since 4.3
 	 */
 	protected final List<HandlerMethodReturnValueHandler> getReturnValueHandlers() {
@@ -688,27 +690,23 @@ protected final List<HandlerMethodReturnValueHandler> getReturnValueHandlers() {
 	}
 
 	/**
-	 * Add custom {@link HandlerMethodReturnValueHandler}s in addition to the
-	 * ones registered by default.
-	 * <p>Custom return value handlers are invoked before built-in ones except
-	 * for those that rely on the presence of annotations (e.g.
-	 * {@code @ResponseBody}, {@code @ModelAttribute}, etc.).
-	 * The latter can be customized by configuring the
+	 * Add custom {@link HandlerMethodReturnValueHandler HandlerMethodReturnValueHandlers}
+	 * in addition to the ones registered by default.
+	 * <p>Custom return value handlers are invoked before built-in ones except for
+	 * those that rely on the presence of annotations (e.g. {@code @ResponseBody},
+	 * {@code @ModelAttribute}, etc). The latter can be customized by configuring the
 	 * {@link RequestMappingHandlerAdapter} directly.
-	 * @param returnValueHandlers the list of custom handlers;
-	 * initially an empty list.
+	 * @param returnValueHandlers the list of custom handlers (initially an empty list)
 	 */
 	protected void addReturnValueHandlers(List<HandlerMethodReturnValueHandler> returnValueHandlers) {
 	}
 
 	/**
-	 * Provides access to the shared {@link HttpMessageConverter}s used by the
-	 * {@link RequestMappingHandlerAdapter} and the
+	 * Provides access to the shared {@link HttpMessageConverter HttpMessageConverters}
+	 * used by the {@link RequestMappingHandlerAdapter} and the
 	 * {@link ExceptionHandlerExceptionResolver}.
-	 * This method cannot be overridden.
-	 * Use {@link #configureMessageConverters(List)} instead.
-	 * Also see {@link #addDefaultHttpMessageConverters(List)} that can be
-	 * used to add default message converters.
+	 * <p>This method cannot be overridden; use {@link #configureMessageConverters} instead.
+	 * Also see {@link #addDefaultHttpMessageConverters} for adding default message converters.
 	 */
 	protected final List<HttpMessageConverter<?>> getMessageConverters() {
 		if (this.messageConverters == null) {
@@ -723,32 +721,30 @@ protected final List<HttpMessageConverter<?>> getMessageConverters() {
 	}
 
 	/**
-	 * Override this method to add custom {@link HttpMessageConverter}s to use
-	 * with the {@link RequestMappingHandlerAdapter} and the
-	 * {@link ExceptionHandlerExceptionResolver}. Adding converters to the
-	 * list turns off the default converters that would otherwise be registered
-	 * by default. Also see {@link #addDefaultHttpMessageConverters(List)} that
-	 * can be used to add default message converters.
-	 * @param converters a list to add message converters to;
-	 * initially an empty list.
+	 * Override this method to add custom {@link HttpMessageConverter HttpMessageConverters}
+	 * to use with the {@link RequestMappingHandlerAdapter} and the
+	 * {@link ExceptionHandlerExceptionResolver}.
+	 * <p>Adding converters to the list turns off the default converters that would
+	 * otherwise be registered by default. Also see {@link #addDefaultHttpMessageConverters}
+	 * for adding default message converters.
+	 * @param converters a list to add message converters to (initially an empty list)
 	 */
 	protected void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
 	}
 
 	/**
-	 * Override this method to extend or modify the list of converters after it
-	 * has been configured. This may be useful for example to allow default
-	 * converters to be registered and then insert a custom converter through
-	 * this method.
-	 * @param converters the list of configured converters to extend.
+	 * Override this method to extend or modify the list of converters after it has
+	 * been configured. This may be useful for example to allow default converters
+	 * to be registered and then insert a custom converter through this method.
+	 * @param converters the list of configured converters to extend
 	 * @since 4.1.3
 	 */
 	protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
 	}
 
 	/**
 	 * Adds a set of default HttpMessageConverter instances to the given list.
-	 * Subclasses can call this method from {@link #configureMessageConverters(List)}.
+	 * Subclasses can call this method from {@link #configureMessageConverters}.
 	 * @param messageConverters the list to add the default message converters to
 	 */
 	protected final void addDefaultHttpMessageConverters(List<HttpMessageConverter<?>> messageConverters) {
@@ -813,14 +809,12 @@ public SimpleControllerHandlerAdapter simpleControllerHandlerAdapter() {
 	}
 
 	/**
-	 * Returns a {@link HandlerExceptionResolverComposite} containing a list
-	 * of exception resolvers obtained either through
-	 * {@link #configureHandlerExceptionResolvers(List)} or through
-	 * {@link #addDefaultHandlerExceptionResolvers(List)}.
-	 * <p><strong>Note:</strong> This method cannot be made final due to CGLib
-	 * constraints. Rather than overriding it, consider overriding
-	 * {@link #configureHandlerExceptionResolvers(List)}, which allows
-	 * providing a list of resolvers.
+	 * Returns a {@link HandlerExceptionResolverComposite} containing a list of exception
+	 * resolvers obtained either through {@link #configureHandlerExceptionResolvers} or
+	 * through {@link #addDefaultHandlerExceptionResolvers}.
+	 * <p><strong>Note:</strong> This method cannot be made final due to CGLIB constraints.
+	 * Rather than overriding it, consider overriding {@link #configureHandlerExceptionResolvers}
+	 * which allows for providing a list of resolvers.
 	 */
 	@Bean
 	public HandlerExceptionResolver handlerExceptionResolver() {
@@ -838,29 +832,29 @@ public HandlerExceptionResolver handlerExceptionResolver() {
 
 	/**
 	 * Override this method to configure the list of
-	 * {@link HandlerExceptionResolver}s to use. Adding resolvers to the list
-	 * turns off the default resolvers that would otherwise be registered by
-	 * default. Also see {@link #addDefaultHandlerExceptionResolvers(List)}
+	 * {@link HandlerExceptionResolver HandlerExceptionResolvers} to use.
+	 * <p>Adding resolvers to the list turns off the default resolvers that would otherwise
+	 * be registered by default. Also see {@link #addDefaultHandlerExceptionResolvers}
 	 * that can be used to add the default exception resolvers.
-	 * @param exceptionResolvers a list to add exception resolvers to;
-	 * initially an empty list.
+	 * @param exceptionResolvers a list to add exception resolvers to (initially an empty list)
 	 */
 	protected void configureHandlerExceptionResolvers(List<HandlerExceptionResolver> exceptionResolvers) {
 	}
 
 	/**
 	 * Override this method to extend or modify the list of
-	 * {@link HandlerExceptionResolver}s after it has been configured. This may
-	 * be useful for example to allow default resolvers to be registered and then
-	 * insert a custom one through this method.
+	 * {@link HandlerExceptionResolver HandlerExceptionResolvers} after it has been configured.
+	 * <p>This may be useful for example to allow default resolvers to be registered
+	 * and then insert a custom one through this method.
 	 * @param exceptionResolvers the list of configured resolvers to extend.
 	 * @since 4.3
 	 */
 	protected void extendHandlerExceptionResolvers(List<HandlerExceptionResolver> exceptionResolvers) {
 	}
 
 	/**
-	 * A method available to subclasses for adding default {@link HandlerExceptionResolver}s.
+	 * A method available to subclasses for adding default
+	 * {@link HandlerExceptionResolver HandlerExceptionResolvers}.
 	 * <p>Adds the following exception resolvers:
 	 * <ul>
 	 * <li>{@link ExceptionHandlerExceptionResolver} for handling exceptions through
@@ -963,7 +957,8 @@ protected final Map<String, CorsConfiguration> getCorsConfigurations() {
 	protected void addCorsMappings(CorsRegistry registry) {
 	}
 
-	@Bean @Lazy
+	@Bean
+	@Lazy
 	public HandlerMappingIntrospector mvcHandlerMappingIntrospector() {
 		return new HandlerMappingIntrospector();
 	}

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerMapping.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -109,6 +109,13 @@ public void setContentNegotiationManager(ContentNegotiationManager contentNegoti
 		this.contentNegotiationManager = contentNegotiationManager;
 	}
 
+	/**
+	 * Return the configured {@link ContentNegotiationManager}.
+	 */
+	public ContentNegotiationManager getContentNegotiationManager() {
+		return this.contentNegotiationManager;
+	}
+
 	@Override
 	public void setEmbeddedValueResolver(StringValueResolver resolver) {
 		this.embeddedValueResolver = resolver;
@@ -149,13 +156,6 @@ public boolean useTrailingSlashMatch() {
 		return this.useTrailingSlashMatch;
 	}
 
-	/**
-	 * Return the configured {@link ContentNegotiationManager}.
-	 */
-	public ContentNegotiationManager getContentNegotiationManager() {
-		return this.contentNegotiationManager;
-	}
-
 	/**
 	 * Return the file extensions to use for suffix pattern matching.
 	 */
@@ -166,7 +166,8 @@ public List<String> getFileExtensions() {
 
 	/**
 	 * {@inheritDoc}
-	 * Expects a handler to have a type-level @{@link Controller} annotation.
+	 * <p>Expects a handler to have either a type-level @{@link Controller}
+	 * annotation or a type-level @{@link RequestMapping} annotation.
 	 */
 	@Override
 	protected boolean isHandler(Class<?> beanType) {