package org.springframework.util;
 
import java.util.Comparator;
import java.util.Map;
 
public interface PathMatcher {
 
    /**
     * Does the given path represent a pattern that can be matched
     * by an implementation of this interface?
     * 判斷指定的路徑 path 是否是一個 pattern(模式)
     * 如果返回值是 false，也就是說 path 不是一個模式，而是一個靜態(tài)路徑(真正的路徑字符串),
     * 那么就不用調(diào)用方法 #match 了，因為對于靜態(tài)路徑的匹配，直接使用字符串等號比較就足夠了。
     * @param path the path String to check
     * @return true if the given path represents a pattern
     */
    boolean isPattern(String path);
 
    /**
     * Match the given path against the given pattern,
     * according to this PathMatcher's matching strategy.
     * 根據(jù)當(dāng)前 PathMatcher 的匹配策略，檢查指定的徑 path 和指定的模式 pattern 是否匹配
     * @param 用于檢測路徑字符串是否匹配于某個模式時所用的模式
     * @param path 需要被檢測的路徑字符串
     * @return true 表示匹配， false 表示不匹配
     */
    boolean match(String pattern, String path);
 
    /**
     * Match the given  path against the corresponding part of the given
     * pattern, according to this PathMatcher's matching strategy.
     * 根據(jù)當(dāng)前 PathMatcher 的匹配策略，檢查指定的徑 path 和指定的模式 pattern 是否之間
     * 是否為前綴匹配
     * @param pattern the pattern to match against
     * @param path the path String to test
     * @return true 表示匹配， false 表示不匹配
     */
    boolean matchStart(String pattern, String path);
 
    /**
     * Given a pattern and a full path, determine the pattern-mapped part.
     * 給定一個模式 pattern 和一個全路徑 path，判斷路徑中和模式匹配的部分。
     *
     * This method is supposed to find out which part of the path is matched
     * dynamically through an actual pattern, that is, it strips off a statically
     * defined leading path from the given full path, returning only the actually
     * pattern-matched part of the path.
     * 該方法用于發(fā)現(xiàn)路徑中的哪一部分是和模式能動態(tài)匹配上的部分。它會去除路徑中開頭靜態(tài)部分，
     * 僅僅返回那部分真正和模式匹配的上的部分。
     * 例子 : "myroot/*.html" 為 pattern , "myroot/myfile.html" 為路徑，
     *  則該方法返回 "myfile.html".  
     * 具體的檢測規(guī)則根據(jù)當(dāng)前 PathMatcher 的匹配策略來頂。    
     * A simple implementation may return the given full path as-is in case
     * of an actual pattern, and the empty String in case of the pattern not
     * containing any dynamic parts (i.e. the pattern parameter being
     * a static path that wouldn't qualify as an actual #isPattern pattern.
     * A sophisticated implementation will differentiate between the static parts
     * and the dynamic parts of the given path pattern.
     * @param pattern the path pattern
     * @param path the full path to introspect
     * @return the pattern-mapped part of the given path
     * (never null)
     */
    String extractPathWithinPattern(String pattern, String path);
 
    /**
     * Given a pattern and a full path, extract the URI template variables. URI template
     * variables are expressed through curly brackets ('{' and '}').
     * 給定一個模式和一個路徑，提取其中的 URI 模板變量信息。URI模板變量表達式格式為 "{variable}"
     *      
     * 例子 : pattern  為 "/hotels/{hotel}" ，路徑為 "/hotels/1", 則該方法會返回一個 map ，
     * 內(nèi)容為 : "hotel"->"1".
     * @param pattern the path pattern, possibly containing URI templates
     * @param path the full path to extract template variables from
     * @return a map, containing variable names as keys; variables values as values
     */
    Map<String, String> extractUriTemplateVariables(String pattern, String path);
 
    /**
     * Given a full path, returns a Comparator suitable for sorting patterns
     * in order of explicitness for that path.
     * The full algorithm used depends on the underlying implementation,
     * but generally, the returned Comparator will sort a list so that more 
     * specific patterns come before generic patterns.
     * @param path the full path to use for comparison
     * @return a comparator capable of sorting patterns in order of explicitness
     */
    Comparator<String> getPatternComparator(String path);
 
    /**
     * Combines two patterns into a new pattern that is returned.
     * The full algorithm used for combining the two pattern depends on the underlying implementation.
     * 合并兩個模式。具體合并的算法由實現(xiàn)類決定。
     * @param pattern1 the first pattern
     * @param pattern2 the second pattern
     * @return the combination of the two patterns
     * @throws IllegalArgumentException when the two patterns cannot be combined
     */
    String combine(String pattern1, String pattern2);
 
}

System.out.println( matcher.match("/usr/name?", "/usr/name1") );  //true
System.out.println( matcher.match("/usr/name?", "/usr/name111") );  //false

System.out.println( matcher.match("/usr/*", "/usr/list")); //true
System.out.println( matcher.match("/usr/*", "/usr/list/again")); //false
System.out.println( matcher.match("/usr/*.app", "/usr/list.app")); //true
System.out.println( matcher.match("/usr/*.app", "/usr/list.html")); //false

System.out.println( matcher.match("/usr/**", "/usr/list") );  //true
System.out.println( matcher.match("/usr/**", "/usr/list/again") );  //true

System.out.println( matcher.match("/usr/{name}/{age}", "/usr/張三/12") );  //true
System.out.println( matcher.match("/usr/{name}/{age}", "/usr/張三") );  //false

/**
 * extractPathWithinPattern 返回符合匹配的部分路徑，去除路徑開頭靜態(tài)部分
 **/
System.out.println( matcher.extractPathWithinPattern("/usr/*", "/usr/list") );   //list
System.out.println( matcher.extractPathWithinPattern("/usr/*/again", "/usr/list/again/age") );   // list/again/age
System.out.println( matcher.extractPathWithinPattern("/usr/*.html", "/usr/list") );  //list
System.out.println( matcher.extractPathWithinPattern("/usr/*.html", "/usr/list.html") );  //list.html

System.out.println( matcher.extractUriTemplateVariables("/usr/{name}/{age}", "/usr/張三/12") ); //{name=張三, age=12}