001/* 002 * Copyright 2002-2019 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.util; 018 019import java.util.Comparator; 020import java.util.Map; 021 022/** 023 * Strategy interface for {@code String}-based path matching. 024 * 025 * <p>Used by {@link org.springframework.core.io.support.PathMatchingResourcePatternResolver}, 026 * {@link org.springframework.web.servlet.handler.AbstractUrlHandlerMapping}, 027 * and {@link org.springframework.web.servlet.mvc.WebContentInterceptor}. 028 * 029 * <p>The default implementation is {@link AntPathMatcher}, supporting the 030 * Ant-style pattern syntax. 031 * 032 * @author Juergen Hoeller 033 * @since 1.2 034 * @see AntPathMatcher 035 */ 036public interface PathMatcher { 037 038 /** 039 * Does the given {@code path} represent a pattern that can be matched 040 * by an implementation of this interface? 041 * <p>If the return value is {@code false}, then the {@link #match} 042 * method does not have to be used because direct equality comparisons 043 * on the static path Strings will lead to the same result. 044 * @param path the path to check 045 * @return {@code true} if the given {@code path} represents a pattern 046 */ 047 boolean isPattern(String path); 048 049 /** 050 * Match the given {@code path} against the given {@code pattern}, 051 * according to this PathMatcher's matching strategy. 052 * @param pattern the pattern to match against 053 * @param path the path to test 054 * @return {@code true} if the supplied {@code path} matched, 055 * {@code false} if it didn't 056 */ 057 boolean match(String pattern, String path); 058 059 /** 060 * Match the given {@code path} against the corresponding part of the given 061 * {@code pattern}, according to this PathMatcher's matching strategy. 062 * <p>Determines whether the pattern at least matches as far as the given base 063 * path goes, assuming that a full path may then match as well. 064 * @param pattern the pattern to match against 065 * @param path the path to test 066 * @return {@code true} if the supplied {@code path} matched, 067 * {@code false} if it didn't 068 */ 069 boolean matchStart(String pattern, String path); 070 071 /** 072 * Given a pattern and a full path, determine the pattern-mapped part. 073 * <p>This method is supposed to find out which part of the path is matched 074 * dynamically through an actual pattern, that is, it strips off a statically 075 * defined leading path from the given full path, returning only the actually 076 * pattern-matched part of the path. 077 * <p>For example: For "myroot/*.html" as pattern and "myroot/myfile.html" 078 * as full path, this method should return "myfile.html". The detailed 079 * determination rules are specified to this PathMatcher's matching strategy. 080 * <p>A simple implementation may return the given full path as-is in case 081 * of an actual pattern, and the empty String in case of the pattern not 082 * containing any dynamic parts (i.e. the {@code pattern} parameter being 083 * a static path that wouldn't qualify as an actual {@link #isPattern pattern}). 084 * A sophisticated implementation will differentiate between the static parts 085 * and the dynamic parts of the given path pattern. 086 * @param pattern the path pattern 087 * @param path the full path to introspect 088 * @return the pattern-mapped part of the given {@code path} 089 * (never {@code null}) 090 */ 091 String extractPathWithinPattern(String pattern, String path); 092 093 /** 094 * Given a pattern and a full path, extract the URI template variables. URI template 095 * variables are expressed through curly brackets ('{' and '}'). 096 * <p>For example: For pattern "/hotels/{hotel}" and path "/hotels/1", this method will 097 * return a map containing "hotel"->"1". 098 * @param pattern the path pattern, possibly containing URI templates 099 * @param path the full path to extract template variables from 100 * @return a map, containing variable names as keys; variables values as values 101 */ 102 Map<String, String> extractUriTemplateVariables(String pattern, String path); 103 104 /** 105 * Given a full path, returns a {@link Comparator} suitable for sorting patterns 106 * in order of explicitness for that path. 107 * <p>The full algorithm used depends on the underlying implementation, 108 * but generally, the returned {@code Comparator} will 109 * {@linkplain java.util.List#sort(java.util.Comparator) sort} 110 * a list so that more specific patterns come before generic patterns. 111 * @param path the full path to use for comparison 112 * @return a comparator capable of sorting patterns in order of explicitness 113 */ 114 Comparator<String> getPatternComparator(String path); 115 116 /** 117 * Combines two patterns into a new pattern that is returned. 118 * <p>The full algorithm used for combining the two pattern depends on the underlying implementation. 119 * @param pattern1 the first pattern 120 * @param pattern2 the second pattern 121 * @return the combination of the two patterns 122 * @throws IllegalArgumentException when the two patterns cannot be combined 123 */ 124 String combine(String pattern1, String pattern2); 125 126}