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 routes to a {@linkplain HandlerFunction handler function}.
023 *
024 * @author Arjen Poutsma
025 * @since 5.2
026 * @param <T> the type of the {@linkplain HandlerFunction handler function} to route to
027 * @see RouterFunctions
028 */
029@FunctionalInterface
030public interface RouterFunction<T extends ServerResponse> {
031
032        /**
033         * Return the {@linkplain HandlerFunction handler function} that matches the given request.
034         * @param request the request to route
035         * @return an {@code Optional} describing the {@code HandlerFunction} that matches this request,
036         * or an empty {@code Optional} if there is no match
037         */
038        Optional<HandlerFunction<T>> route(ServerRequest request);
039
040        /**
041         * Return a composed routing function that first invokes this function,
042         * and then invokes the {@code other} function (of the same response type {@code T})
043         * if this route had {@linkplain Optional#empty() no result}.
044         * @param other the function of type {@code T} to apply when this function has no result
045         * @return a composed function that first routes with this function and then the
046         * {@code other} function if this function has no result
047         * @see #andOther(RouterFunction)
048         */
049        default RouterFunction<T> and(RouterFunction<T> other) {
050                return new RouterFunctions.SameComposedRouterFunction<>(this, other);
051        }
052
053        /**
054         * Return a composed routing function that first invokes this function,
055         * and then invokes the {@code other} function (of a different response type) if this route had
056         * {@linkplain Optional#empty() no result}.
057         * @param other the function to apply when this function has no result
058         * @return a composed function that first routes with this function and then the
059         * {@code other} function if this function has no result
060         * @see #and(RouterFunction)
061         */
062        default RouterFunction<?> andOther(RouterFunction<?> other) {
063                return new RouterFunctions.DifferentComposedRouterFunction(this, other);
064        }
065
066        /**
067         * Return a composed routing function that routes to the given handler function if this
068         * route does not match and the given request predicate applies. This method is a convenient
069         * combination of {@link #and(RouterFunction)} and
070         * {@link RouterFunctions#route(RequestPredicate, HandlerFunction)}.
071         * @param predicate the predicate to test if this route does not match
072         * @param handlerFunction the handler function to route to if this route does not match and
073         * the predicate applies
074         * @return a composed function that route to {@code handlerFunction} if this route does not
075         * match and if {@code predicate} applies
076         */
077        default RouterFunction<T> andRoute(RequestPredicate predicate, HandlerFunction<T> handlerFunction) {
078                return and(RouterFunctions.route(predicate, handlerFunction));
079        }
080
081        /**
082         * Return a composed routing function that routes to the given router function if this
083         * route does not match and the given request predicate applies. This method is a convenient
084         * combination of {@link #and(RouterFunction)} and
085         * {@link RouterFunctions#nest(RequestPredicate, RouterFunction)}.
086         * @param predicate the predicate to test if this route does not match
087         * @param routerFunction the router function to route to if this route does not match and
088         * the predicate applies
089         * @return a composed function that route to {@code routerFunction} if this route does not
090         * match and if {@code predicate} applies
091         */
092        default RouterFunction<T> andNest(RequestPredicate predicate, RouterFunction<T> routerFunction) {
093                return and(RouterFunctions.nest(predicate, routerFunction));
094        }
095
096        /**
097         * Filter all {@linkplain HandlerFunction handler functions} routed by this function with the given
098         * {@linkplain HandlerFilterFunction filter function}.
099         * @param <S> the filter return type
100         * @param filterFunction the filter to apply
101         * @return the filtered routing function
102         */
103        default <S extends ServerResponse> RouterFunction<S> filter(HandlerFilterFunction<T, S> filterFunction) {
104                return new RouterFunctions.FilteredRouterFunction<>(this, filterFunction);
105        }
106
107        /**
108         * Accept the given visitor. Default implementation calls
109         * {@link RouterFunctions.Visitor#unknown(RouterFunction)}; composed {@code RouterFunction}
110         * implementations are expected to call {@code accept} for all components that make up this
111         * router function.
112         * @param visitor the visitor to accept
113         */
114        default void accept(RouterFunctions.Visitor visitor) {
115                visitor.unknown(this);
116        }
117}