Rename RouterFunctions.subroute() to nest()

This commit renames the `RouterFunctions.subroute()` method to `nest()`, to
better represent what it does.

Issue: SPR-14954

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/RequestPredicate.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@ import org.springframework.util.Assert;
  * @since 5.0
  * @see RequestPredicates
  * @see RouterFunctions#route(RequestPredicate, HandlerFunction)
- * @see RouterFunctions#subroute(RequestPredicate, RouterFunction)
+ * @see RouterFunctions#nest(RequestPredicate, RouterFunction)
  */
 @FunctionalInterface
 public interface RequestPredicate {

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/RouterFunction.java

@@ -66,20 +66,35 @@ public interface RouterFunction<T extends ServerResponse> {
 	}
 
 	/**
-	 * Return a composed routing function that first invokes this function,
-	 * and then routes to the given handler function if the given request predicate applies. This
-	 * method is a convenient combination of {@link #and(RouterFunction)} and
+	 * Return a composed routing function that routes to the given handler function if this
+	 * route does not match and the given request predicate applies. This method is a convenient
+	 * combination of {@link #and(RouterFunction)} and
 	 * {@link RouterFunctions#route(RequestPredicate, HandlerFunction)}.
-	 * @param predicate the predicate to test
-	 * @param handlerFunction the handler function to route to
-	 * @return a composed function that first routes with this function and then the function
-	 * created from {@code predicate} and {@code handlerFunction} if this
-	 * function has no result
+	 * @param predicate the predicate to test if this route does not match
+	 * @param handlerFunction the handler function to route to if this route does not match and
+	 * the predicate applies
+	 * @return a composed function that route to {@code handlerFunction} if this route does not
+	 * match and if {@code predicate} applies
 	 */
 	default RouterFunction<T> andRoute(RequestPredicate predicate, HandlerFunction<T> handlerFunction) {
 		return and(RouterFunctions.route(predicate, handlerFunction));
 	}
 
+	/**
+	 * Return a composed routing function that routes to the given router function if this
+	 * route does not match and the given request predicate applies. This method is a convenient
+	 * combination of {@link #and(RouterFunction)} and
+	 * {@link RouterFunctions#nest(RequestPredicate, RouterFunction)}.
+	 * @param predicate the predicate to test if this route does not match
+	 * @param routerFunction the router function to route to if this route does not match and
+	 * the predicate applies
+	 * @return a composed function that route to {@code routerFunction} if this route does not
+	 * match and if {@code predicate} applies
+	 */
+	default RouterFunction<T> andNest(RequestPredicate predicate, RouterFunction<T> routerFunction) {
+		return and(RouterFunctions.nest(predicate, routerFunction));
+	}
+
 	/**
 	 * Filter all {@linkplain HandlerFunction handler functions} routed by this function with the given
 	 * {@linkplain HandlerFilterFunction filter function}.

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/RouterFunctions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,7 +37,7 @@ import org.springframework.web.server.adapter.WebHttpHandlerBuilder;
  * Exposes routing functionality, such as to
  * {@linkplain #route(RequestPredicate, HandlerFunction) create} a {@code RouterFunction} given a
  * {@code RequestPredicate} and {@code HandlerFunction}, and to do further
- * {@linkplain #subroute(RequestPredicate, RouterFunction) subrouting} on an existing routing
+ * {@linkplain #nest(RequestPredicate, RouterFunction) subrouting} on an existing routing
  * function.
  *
  * <p>Additionally, this class can {@linkplain #toHttpHandler(RouterFunction) transform} a
@@ -69,9 +69,17 @@ public abstract class RouterFunctions {
 
 	/**
 	 * Route to the given handler function if the given request predicate applies.
+	 * <p>For instance, the following example routes GET requests for "/user" to the
+	 * {@code listUsers} method in {@code userController}:
+	 * <pre class="code">
+	 * RouterFunction&lt;ServerResponse&gt; route =
+	 *   RouterFunctions.route(RequestPredicates.GET("/user"),
+	 *     userController::listUsers);
+	 * </pre>
+	 *
 	 * @param predicate the predicate to test
-	 * @param handlerFunction the handler function to route to
-	 * @param <T> the type of the handler function
+	 * @param handlerFunction the handler function to route to if the predicate applies
+	 * @param <T> the type of response returned by the handler function
 	 * @return a router function that routes to {@code handlerFunction} if
 	 * {@code predicate} evaluates to {@code true}
 	 * @see RequestPredicates
@@ -86,15 +94,29 @@ public abstract class RouterFunctions {
 	}
 
 	/**
-	 * Route to the given router function if the given request predicate applies.
+	 * Route to the given router function if the given request predicate applies. This method can be
+	 * used to create <strong>nested routes</strong>, where a group of routes share a common path
+	 * (prefix), header, or other request predicate.
+	 * <p>For instance, the following example first creates a composed route that resolves to
+	 * {@code listUsers} for a GET, and {@code createUser} for a POST. This composed route then gets
+	 * nested with a "/user" path predicate, so that GET requests for "/user" will list users,
+	 * and POST request for "/user" will create a new user.
+	 * <pre class="code">
+	 * RouterFunction&lt;ServerResponse&gt; userRoutes =
+	 *   RouterFunctions.route(RequestPredicates.method(HttpMethod.GET), this::listUsers)
+	 *     .andRoute(RequestPredicates.method(HttpMethod.POST), this::createUser);
+	 *
+	 * RouterFunction&lt;ServerResponse&gt; nestedRoute =
+	 *   RouterFunctions.nest(RequestPredicates.path("/user"),userRoutes);
+	 * </pre>
 	 * @param predicate the predicate to test
-	 * @param routerFunction the router function to route to
-	 * @param <T> the type of the handler function
+	 * @param routerFunction the nested router function to delegate to if the predicate applies
+	 * @param <T> the type of response returned by the handler function
 	 * @return a router function that routes to {@code routerFunction} if
 	 * {@code predicate} evaluates to {@code true}
 	 * @see RequestPredicates
 	 */
-	public static <T extends ServerResponse> RouterFunction<T> subroute(RequestPredicate predicate,
+	public static <T extends ServerResponse> RouterFunction<T> nest(RequestPredicate predicate,
 			RouterFunction<T> routerFunction) {
 
 		Assert.notNull(predicate, "'predicate' must not be null");

spring-webflux/src/test/java/org/springframework/web/reactive/function/server/RouterFunctionsTests.java

@@ -30,8 +30,11 @@ import org.springframework.mock.http.server.reactive.test.MockServerHttpResponse
 import org.springframework.web.reactive.result.view.ViewResolver;
 import org.springframework.web.server.ServerWebExchange;
 
-import static org.junit.Assert.*;
-import static org.mockito.Mockito.*;
+import static org.junit.Assert.assertNotNull;
+import static org.mockito.Mockito.any;
+import static org.mockito.Mockito.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
 
 /**
  * @author Arjen Poutsma
@@ -77,7 +80,7 @@ public class RouterFunctionsTests {
 	}
 
 	@Test
-	public void subrouteMatch() throws Exception {
+	public void nestMatch() throws Exception {
 		HandlerFunction<ServerResponse> handlerFunction = request -> ServerResponse.ok().build();
 		RouterFunction<ServerResponse> routerFunction = request -> Mono.just(handlerFunction);
 
@@ -85,7 +88,7 @@ public class RouterFunctionsTests {
 		RequestPredicate requestPredicate = mock(RequestPredicate.class);
 		when(requestPredicate.test(request)).thenReturn(true);
 
-		RouterFunction<ServerResponse> result = RouterFunctions.subroute(requestPredicate, routerFunction);
+		RouterFunction<ServerResponse> result = RouterFunctions.nest(requestPredicate, routerFunction);
 		assertNotNull(result);
 
 		Mono<HandlerFunction<ServerResponse>> resultHandlerFunction = result.route(request);
@@ -96,7 +99,7 @@ public class RouterFunctionsTests {
 	}
 
 	@Test
-	public void subrouteNoMatch() throws Exception {
+	public void nestNoMatch() throws Exception {
 		HandlerFunction<ServerResponse> handlerFunction = request -> ServerResponse.ok().build();
 		RouterFunction<ServerResponse> routerFunction = request -> Mono.just(handlerFunction);
 
@@ -104,7 +107,7 @@ public class RouterFunctionsTests {
 		RequestPredicate requestPredicate = mock(RequestPredicate.class);
 		when(requestPredicate.test(request)).thenReturn(false);
 
-		RouterFunction<ServerResponse> result = RouterFunctions.subroute(requestPredicate, routerFunction);
+		RouterFunction<ServerResponse> result = RouterFunctions.nest(requestPredicate, routerFunction);
 		assertNotNull(result);
 
 		Mono<HandlerFunction<ServerResponse>> resultHandlerFunction = result.route(request);