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 022import org.springframework.lang.Nullable; 023 024/** 025 * Contract for matching routes to patterns. 026 * 027 * <p>Equivalent to {@link PathMatcher}, but enables use of parsed representations 028 * of routes and patterns for efficiency reasons in scenarios where routes from 029 * incoming messages are continuously matched against a large number of message 030 * handler patterns. 031 * 032 * @author Rossen Stoyanchev 033 * @since 5.2 034 * @see PathMatcher 035 */ 036public interface RouteMatcher { 037 038 /** 039 * Return a parsed representation of the given route. 040 * @param routeValue the route to parse 041 * @return the parsed representation of the route 042 */ 043 Route parseRoute(String routeValue); 044 045 /** 046 * Whether the given {@code route} contains pattern syntax which requires 047 * the {@link #match(String, Route)} method, or if it is a regular String 048 * that could be compared directly to others. 049 * @param route the route to check 050 * @return {@code true} if the given {@code route} represents a pattern 051 */ 052 boolean isPattern(String route); 053 054 /** 055 * Combines two patterns into a single pattern. 056 * @param pattern1 the first pattern 057 * @param pattern2 the second pattern 058 * @return the combination of the two patterns 059 * @throws IllegalArgumentException when the two patterns cannot be combined 060 */ 061 String combine(String pattern1, String pattern2); 062 063 /** 064 * Match the given route against the given pattern. 065 * @param pattern the pattern to try to match 066 * @param route the route to test against 067 * @return {@code true} if there is a match, {@code false} otherwise 068 */ 069 boolean match(String pattern, Route route); 070 071 /** 072 * Match the pattern to the route and extract template variables. 073 * @param pattern the pattern, possibly containing templates variables 074 * @param route the route to extract template variables from 075 * @return a map with template variables and values 076 */ 077 @Nullable 078 Map<String, String> matchAndExtract(String pattern, Route route); 079 080 /** 081 * Given a route, return a {@link Comparator} suitable for sorting patterns 082 * in order of explicitness for that route, so that more specific patterns 083 * come before more generic ones. 084 * @param route the full path to use for comparison 085 * @return a comparator capable of sorting patterns in order of explicitness 086 */ 087 Comparator<String> getPatternComparator(Route route); 088 089 090 /** 091 * A parsed representation of a route. 092 */ 093 interface Route { 094 095 /** 096 * The original route value. 097 */ 098 String value(); 099 } 100 101}