001/*
002 * Copyright 2002-2016 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.mvc.condition;
018
019import javax.servlet.http.HttpServletRequest;
020
021import org.springframework.lang.Nullable;
022
023/**
024 * Contract for request mapping conditions.
025 *
026 * <p>Request conditions can be combined via {@link #combine(Object)}, matched to
027 * a request via {@link #getMatchingCondition(HttpServletRequest)}, and compared
028 * to each other via {@link #compareTo(Object, HttpServletRequest)} to determine
029 * which is a closer match for a given request.
030 *
031 * @author Rossen Stoyanchev
032 * @author Arjen Poutsma
033 * @since 3.1
034 * @param <T> the type of objects that this RequestCondition can be combined
035 * with and compared to
036 */
037public interface RequestCondition<T> {
038
039        /**
040         * Combine this condition with another such as conditions from a
041         * type-level and method-level {@code @RequestMapping} annotation.
042         * @param other the condition to combine with.
043         * @return a request condition instance that is the result of combining
044         * the two condition instances.
045         */
046        T combine(T other);
047
048        /**
049         * Check if the condition matches the request returning a potentially new
050         * instance created for the current request. For example a condition with
051         * multiple URL patterns may return a new instance only with those patterns
052         * that match the request.
053         * <p>For CORS pre-flight requests, conditions should match to the would-be,
054         * actual request (e.g. URL pattern, query parameters, and the HTTP method
055         * from the "Access-Control-Request-Method" header). If a condition cannot
056         * be matched to a pre-flight request it should return an instance with
057         * empty content thus not causing a failure to match.
058         * @return a condition instance in case of a match or {@code null} otherwise.
059         */
060        @Nullable
061        T getMatchingCondition(HttpServletRequest request);
062
063        /**
064         * Compare this condition to another condition in the context of
065         * a specific request. This method assumes both instances have
066         * been obtained via {@link #getMatchingCondition(HttpServletRequest)}
067         * to ensure they have content relevant to current request only.
068         */
069        int compareTo(T other, HttpServletRequest request);
070
071}