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.web.servlet.function;
018
019import java.util.Optional;
020
021/**
022 * Represents a function that evaluates on a given {@link ServerRequest}.
023 * Instances of this function that evaluate on common request properties
024 * can be found in {@link RequestPredicates}.
025 *
026 * @author Arjen Poutsma
027 * @since 5.2
028 * @see RequestPredicates
029 * @see RouterFunctions#route(RequestPredicate, HandlerFunction)
030 * @see RouterFunctions#nest(RequestPredicate, RouterFunction)
031 */
032@FunctionalInterface
033public interface RequestPredicate {
034
035        /**
036         * Evaluate this predicate on the given request.
037         * @param request the request to match against
038         * @return {@code true} if the request matches the predicate; {@code false} otherwise
039         */
040        boolean test(ServerRequest request);
041
042        /**
043         * Return a composed request predicate that tests against both this predicate AND
044         * the {@code other} predicate. When evaluating the composed predicate, if this
045         * predicate is {@code false}, then the {@code other} predicate is not evaluated.
046         * @param other a predicate that will be logically-ANDed with this predicate
047         * @return a predicate composed of this predicate AND the {@code other} predicate
048         */
049        default RequestPredicate and(RequestPredicate other) {
050                return new RequestPredicates.AndRequestPredicate(this, other);
051        }
052
053        /**
054         * Return a predicate that represents the logical negation of this predicate.
055         * @return a predicate that represents the logical negation of this predicate
056         */
057        default RequestPredicate negate() {
058                return new RequestPredicates.NegateRequestPredicate(this);
059        }
060
061        /**
062         * Return a composed request predicate that tests against both this predicate OR
063         * the {@code other} predicate. When evaluating the composed predicate, if this
064         * predicate is {@code true}, then the {@code other} predicate is not evaluated.
065         * @param other a predicate that will be logically-ORed with this predicate
066         * @return a predicate composed of this predicate OR the {@code other} predicate
067         */
068        default RequestPredicate or(RequestPredicate other) {
069                return new RequestPredicates.OrRequestPredicate(this, other);
070        }
071
072        /**
073         * Transform the given request into a request used for a nested route. For instance,
074         * a path-based predicate can return a {@code ServerRequest} with a the path remaining
075         * after a match.
076         * <p>The default implementation returns an {@code Optional} wrapping the given request if
077         * {@link #test(ServerRequest)} evaluates to {@code true}; or {@link Optional#empty()}
078         * if it evaluates to {@code false}.
079         * @param request the request to be nested
080         * @return the nested request
081         * @see RouterFunctions#nest(RequestPredicate, RouterFunction)
082         */
083        default Optional<ServerRequest> nest(ServerRequest request) {
084                return (test(request) ? Optional.of(request) : Optional.empty());
085        }
086
087        /**
088         * Accept the given visitor. Default implementation calls
089         * {@link RequestPredicates.Visitor#unknown(RequestPredicate)}; composed {@code RequestPredicate}
090         * implementations are expected to call {@code accept} for all components that make up this
091         * request predicate.
092         * @param visitor the visitor to accept
093         */
094        default void accept(RequestPredicates.Visitor visitor) {
095                visitor.unknown(this);
096        }
097}