001/*
002 * Copyright 2002-2016 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.servlet.config.annotation;
018
019import java.util.List;
020
021import org.springframework.core.convert.converter.Converter;
022import org.springframework.format.Formatter;
023import org.springframework.format.FormatterRegistry;
024import org.springframework.http.converter.HttpMessageConverter;
025import org.springframework.validation.MessageCodesResolver;
026import org.springframework.validation.Validator;
027import org.springframework.web.method.support.HandlerMethodArgumentResolver;
028import org.springframework.web.method.support.HandlerMethodReturnValueHandler;
029import org.springframework.web.servlet.DispatcherServlet;
030import org.springframework.web.servlet.HandlerExceptionResolver;
031import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter;
032
033/**
034 * Defines callback methods to customize the Java-based configuration for
035 * Spring MVC enabled via {@code @EnableWebMvc}.
036 *
037 * <p>{@code @EnableWebMvc}-annotated configuration classes may implement
038 * this interface to be called back and given a chance to customize the
039 * default configuration. Consider extending {@link WebMvcConfigurerAdapter},
040 * which provides a stub implementation of all interface methods.
041 *
042 * @author Rossen Stoyanchev
043 * @author Keith Donald
044 * @author David Syer
045 * @since 3.1
046 */
047public interface WebMvcConfigurer {
048
049        /**
050         * Helps with configuring HandlerMappings path matching options such as trailing slash match,
051         * suffix registration, path matcher and path helper.
052         * Configured path matcher and path helper instances are shared for:
053         * <ul>
054         * <li>RequestMappings</li>
055         * <li>ViewControllerMappings</li>
056         * <li>ResourcesMappings</li>
057         * </ul>
058         * @since 4.0.3
059         */
060        void configurePathMatch(PathMatchConfigurer configurer);
061
062        /**
063         * Configure content negotiation options.
064         */
065        void configureContentNegotiation(ContentNegotiationConfigurer configurer);
066
067        /**
068         * Configure asynchronous request handling options.
069         */
070        void configureAsyncSupport(AsyncSupportConfigurer configurer);
071
072        /**
073         * Configure a handler to delegate unhandled requests by forwarding to the
074         * Servlet container's "default" servlet. A common use case for this is when
075         * the {@link DispatcherServlet} is mapped to "/" thus overriding the
076         * Servlet container's default handling of static resources.
077         */
078        void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer);
079
080        /**
081         * Add {@link Converter}s and {@link Formatter}s in addition to the ones
082         * registered by default.
083         */
084        void addFormatters(FormatterRegistry registry);
085
086        /**
087         * Add Spring MVC lifecycle interceptors for pre- and post-processing of
088         * controller method invocations. Interceptors can be registered to apply
089         * to all requests or be limited to a subset of URL patterns.
090         * <p><strong>Note</strong> that interceptors registered here only apply to
091         * controllers and not to resource handler requests. To intercept requests for
092         * static resources either declare a
093         * {@link org.springframework.web.servlet.handler.MappedInterceptor MappedInterceptor}
094         * bean or switch to advanced configuration mode by extending
095         * {@link org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport
096         * WebMvcConfigurationSupport} and then override {@code resourceHandlerMapping}.
097         */
098        void addInterceptors(InterceptorRegistry registry);
099
100        /**
101         * Add handlers to serve static resources such as images, js, and, css
102         * files from specific locations under web application root, the classpath,
103         * and others.
104         */
105        void addResourceHandlers(ResourceHandlerRegistry registry);
106
107        /**
108         * Configure cross origin requests processing.
109         * @since 4.2
110         */
111        void addCorsMappings(CorsRegistry registry);
112
113        /**
114         * Configure simple automated controllers pre-configured with the response
115         * status code and/or a view to render the response body. This is useful in
116         * cases where there is no need for custom controller logic -- e.g. render a
117         * home page, perform simple site URL redirects, return a 404 status with
118         * HTML content, a 204 with no content, and more.
119         */
120        void addViewControllers(ViewControllerRegistry registry);
121
122        /**
123         * Configure view resolvers to translate String-based view names returned from
124         * controllers into concrete {@link org.springframework.web.servlet.View}
125         * implementations to perform rendering with.
126         * @since 4.1
127         */
128        void configureViewResolvers(ViewResolverRegistry registry);
129
130        /**
131         * Add resolvers to support custom controller method argument types.
132         * <p>This does not override the built-in support for resolving handler
133         * method arguments. To customize the built-in support for argument
134         * resolution, configure {@link RequestMappingHandlerAdapter} directly.
135         * @param argumentResolvers initially an empty list
136         */
137        void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers);
138
139        /**
140         * Add handlers to support custom controller method return value types.
141         * <p>Using this option does not override the built-in support for handling
142         * return values. To customize the built-in support for handling return
143         * values, configure RequestMappingHandlerAdapter directly.
144         * @param returnValueHandlers initially an empty list
145         */
146        void addReturnValueHandlers(List<HandlerMethodReturnValueHandler> returnValueHandlers);
147
148        /**
149         * Configure the {@link HttpMessageConverter}s to use for reading or writing
150         * to the body of the request or response. If no converters are added, a
151         * default list of converters is registered.
152         * <p><strong>Note</strong> that adding converters to the list, turns off
153         * default converter registration. To simply add a converter without impacting
154         * default registration, consider using the method
155         * {@link #extendMessageConverters(java.util.List)} instead.
156         * @param converters initially an empty list of converters
157         */
158        void configureMessageConverters(List<HttpMessageConverter<?>> converters);
159
160        /**
161         * A hook for extending or modifying the list of converters after it has been
162         * configured. This may be useful for example to allow default converters to
163         * be registered and then insert a custom converter through this method.
164         * @param converters the list of configured converters to extend.
165         * @since 4.1.3
166         */
167        void extendMessageConverters(List<HttpMessageConverter<?>> converters);
168
169        /**
170         * Configure exception resolvers.
171         * <p>The given list starts out empty. If it is left empty, the framework
172         * configures a default set of resolvers, see
173         * {@link WebMvcConfigurationSupport#addDefaultHandlerExceptionResolvers(List)}.
174         * Or if any exception resolvers are added to the list, then the application
175         * effectively takes over and must provide, fully initialized, exception
176         * resolvers.
177         * <p>Alternatively you can use
178         * {@link #extendHandlerExceptionResolvers(List)} which allows you to extend
179         * or modify the list of exception resolvers configured by default.
180         * @param exceptionResolvers initially an empty list
181         * @see #extendHandlerExceptionResolvers(List)
182         * @see WebMvcConfigurationSupport#addDefaultHandlerExceptionResolvers(List)
183         */
184        void configureHandlerExceptionResolvers(List<HandlerExceptionResolver> exceptionResolvers);
185
186        /**
187         * Extending or modify the list of exception resolvers configured by default.
188         * This can be useful for inserting a custom exception resolver without
189         * interfering with default ones.
190         * @param exceptionResolvers the list of configured resolvers to extend
191         * @since 4.3
192         * @see WebMvcConfigurationSupport#addDefaultHandlerExceptionResolvers(List)
193         */
194        void extendHandlerExceptionResolvers(List<HandlerExceptionResolver> exceptionResolvers);
195
196        /**
197         * Provide a custom {@link Validator} instead of the one created by default.
198         * The default implementation, assuming JSR-303 is on the classpath, is:
199         * {@link org.springframework.validation.beanvalidation.OptionalValidatorFactoryBean}.
200         * Leave the return value as {@code null} to keep the default.
201         */
202        Validator getValidator();
203
204        /**
205         * Provide a custom {@link MessageCodesResolver} for building message codes
206         * from data binding and validation error codes. Leave the return value as
207         * {@code null} to keep the default.
208         */
209        MessageCodesResolver getMessageCodesResolver();
210
211}