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}