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