001/*
002 * Copyright 2002-2018 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;
018
019import javax.servlet.http.HttpServletRequest;
020
021import org.springframework.lang.Nullable;
022
023/**
024 * Interface to be implemented by objects that define a mapping between
025 * requests and handler objects.
026 *
027 * <p>This class can be implemented by application developers, although this is not
028 * necessary, as {@link org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping}
029 * and {@link org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping}
030 * are included in the framework. The former is the default if no
031 * HandlerMapping bean is registered in the application context.
032 *
033 * <p>HandlerMapping implementations can support mapped interceptors but do not
034 * have to. A handler will always be wrapped in a {@link HandlerExecutionChain}
035 * instance, optionally accompanied by some {@link HandlerInterceptor} instances.
036 * The DispatcherServlet will first call each HandlerInterceptor's
037 * {@code preHandle} method in the given order, finally invoking the handler
038 * itself if all {@code preHandle} methods have returned {@code true}.
039 *
040 * <p>The ability to parameterize this mapping is a powerful and unusual
041 * capability of this MVC framework. For example, it is possible to write
042 * a custom mapping based on session state, cookie state or many other
043 * variables. No other MVC framework seems to be equally flexible.
044 *
045 * <p>Note: Implementations can implement the {@link org.springframework.core.Ordered}
046 * interface to be able to specify a sorting order and thus a priority for getting
047 * applied by DispatcherServlet. Non-Ordered instances get treated as lowest priority.
048 *
049 * @author Rod Johnson
050 * @author Juergen Hoeller
051 * @see org.springframework.core.Ordered
052 * @see org.springframework.web.servlet.handler.AbstractHandlerMapping
053 * @see org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping
054 * @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping
055 */
056public interface HandlerMapping {
057
058        /**
059         * Name of the {@link HttpServletRequest} attribute that contains the mapped
060         * handler for the best matching pattern.
061         * @since 4.3.21
062         */
063        String BEST_MATCHING_HANDLER_ATTRIBUTE = HandlerMapping.class.getName() + ".bestMatchingHandler";
064
065        /**
066         * Name of the {@link HttpServletRequest} attribute that contains the path
067         * used to look up the matching handler, which depending on the configured
068         * {@link org.springframework.web.util.UrlPathHelper} could be the full path
069         * or without the context path, decoded or not, etc.
070         * @since 5.2
071         */
072        String LOOKUP_PATH = HandlerMapping.class.getName() + ".lookupPath";
073
074        /**
075         * Name of the {@link HttpServletRequest} attribute that contains the path
076         * within the handler mapping, in case of a pattern match, or the full
077         * relevant URI (typically within the DispatcherServlet's mapping) else.
078         * <p>Note: This attribute is not required to be supported by all
079         * HandlerMapping implementations. URL-based HandlerMappings will
080         * typically support it, but handlers should not necessarily expect
081         * this request attribute to be present in all scenarios.
082         */
083        String PATH_WITHIN_HANDLER_MAPPING_ATTRIBUTE = HandlerMapping.class.getName() + ".pathWithinHandlerMapping";
084
085        /**
086         * Name of the {@link HttpServletRequest} attribute that contains the
087         * best matching pattern within the handler mapping.
088         * <p>Note: This attribute is not required to be supported by all
089         * HandlerMapping implementations. URL-based HandlerMappings will
090         * typically support it, but handlers should not necessarily expect
091         * this request attribute to be present in all scenarios.
092         */
093        String BEST_MATCHING_PATTERN_ATTRIBUTE = HandlerMapping.class.getName() + ".bestMatchingPattern";
094
095        /**
096         * Name of the boolean {@link HttpServletRequest} attribute that indicates
097         * whether type-level mappings should be inspected.
098         * <p>Note: This attribute is not required to be supported by all
099         * HandlerMapping implementations.
100         */
101        String INTROSPECT_TYPE_LEVEL_MAPPING = HandlerMapping.class.getName() + ".introspectTypeLevelMapping";
102
103        /**
104         * Name of the {@link HttpServletRequest} attribute that contains the URI
105         * templates map, mapping variable names to values.
106         * <p>Note: This attribute is not required to be supported by all
107         * HandlerMapping implementations. URL-based HandlerMappings will
108         * typically support it, but handlers should not necessarily expect
109         * this request attribute to be present in all scenarios.
110         */
111        String URI_TEMPLATE_VARIABLES_ATTRIBUTE = HandlerMapping.class.getName() + ".uriTemplateVariables";
112
113        /**
114         * Name of the {@link HttpServletRequest} attribute that contains a map with
115         * URI variable names and a corresponding MultiValueMap of URI matrix
116         * variables for each.
117         * <p>Note: This attribute is not required to be supported by all
118         * HandlerMapping implementations and may also not be present depending on
119         * whether the HandlerMapping is configured to keep matrix variable content
120         */
121        String MATRIX_VARIABLES_ATTRIBUTE = HandlerMapping.class.getName() + ".matrixVariables";
122
123        /**
124         * Name of the {@link HttpServletRequest} attribute that contains the set of
125         * producible MediaTypes applicable to the mapped handler.
126         * <p>Note: This attribute is not required to be supported by all
127         * HandlerMapping implementations. Handlers should not necessarily expect
128         * this request attribute to be present in all scenarios.
129         */
130        String PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE = HandlerMapping.class.getName() + ".producibleMediaTypes";
131
132        /**
133         * Return a handler and any interceptors for this request. The choice may be made
134         * on request URL, session state, or any factor the implementing class chooses.
135         * <p>The returned HandlerExecutionChain contains a handler Object, rather than
136         * even a tag interface, so that handlers are not constrained in any way.
137         * For example, a HandlerAdapter could be written to allow another framework's
138         * handler objects to be used.
139         * <p>Returns {@code null} if no match was found. This is not an error.
140         * The DispatcherServlet will query all registered HandlerMapping beans to find
141         * a match, and only decide there is an error if none can find a handler.
142         * @param request current HTTP request
143         * @return a HandlerExecutionChain instance containing handler object and
144         * any interceptors, or {@code null} if no mapping found
145         * @throws Exception if there is an internal error
146         */
147        @Nullable
148        HandlerExecutionChain getHandler(HttpServletRequest request) throws Exception;
149
150}