spring-cloud-gateway/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/java-routes-api.adoc

[[java-routes-api]]
= Java Routes API

Spring Cloud Gateway Server MVC uses the Spring WebMvc.fn https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/function/RouterFunctions.Builder.html[RouterFunctions.Builder] as the default way to create Routes, which are WebMvc.fn https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/function/RouterFunction.html[RouterFunction] instances.

A https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/function/RouterFunctions.Builder.html[`RouterFunctions.Builder`] instance is obtained by calling https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/function/RouterFunctions.html#route()[RouterFunctions.route()]

.GatewaySampleApplication.java
[source,java]
----
import static org.springframework.web.servlet.function.RouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

class SimpleGateway {
    @Bean
    public RouterFunction<ServerResponse> getRoute() {
        return route().GET("/get", http())
            .before(uri("https://example.org"))
            .build();
    }
}
----

There are methods in `RouterFunctions.Builder` for each HTTP methods (GET, POST, etc...) combined with a path predicate, such as `/get` as above. The final parameter is the `HandlerFilterFunction`, in this case `HandlerFunctions.http()`. There are overloaded methods for each HTTP method for additional `RequestPredicate` parameters as well as a generic `route(RequestPredicate, HandlerFunction`) method for general use.

[[gateway-routerfunctions-builder]]
== Gateway MVC implementation of RouterFunctions.Builder

Some advanced filters require some metadata to be added to request attributes. To accommodate this, there is a `org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions` class. `GatewayRouterFunctions.route(String routeId) creates a `RouterFunctions.Builder` instance then adds a 'before' filter to add the `routeId` as request metadata.

.GatewaySampleApplication.java
[source,java]
----
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

class SimpleGateway {
    @Bean
    public RouterFunction<ServerResponse> getRoute() {
        return route("simple_route").GET("/get", http())
            .before(uri("https://example.org"))
            .build();
    }
}
----

[[gateway-handlerfunctions]]
== Gateway MVC Handler Functions


Various `RouterFunctions.Builder` methods require a `HandlerFunction<ServerResponse>`. To create a route that is proxied by the MVC Gateway, `HandlerFunction` implementations are supplied in `org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions`. 

=== HTTP Handler Function
The most basic handler function is `http()` `HandlerFunction`. If a `URI` is supplied as a parameter, that is the `URI` used as the downstream target for sending the HTTP requests (as seen in the example above). If no parameter is passed, the function looks for a `URI` in the `org.springframework.cloud.gateway.server.mvc.common.MvcUtils.GATEWAY_REQUEST_URL_ATTR` request attribute. This allows for dynamic targets such as load balancing to set the `URI`.


WARNING: As of version 4.1.7, `HandlerFunctions.http(String)` and `HandlerFunctions.http(URI)` are now deprecated. Please use `HandlerFunctions.http()` in combination with the `BeforeFilterFunctions.uri()` filter instead. This fixes inconsistencies in dealing with the route url request attribute.

=== Spring Cloud Function Handler Function
By placing https://spring.io/projects/spring-cloud-function[Spring Cloud Function] on the classpath, Spring Cloud Gateway will automatically configure routes to invoke functions you define as beans. The bean names of the functions will be used as the path of the routes.

For example, given the following configuration:

[source,xml]
----
<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-function-context</artifactId>
</dependency>
----

Once Spring Cloud Function dependency is provided the name of the Java function bean becomes the path you can use to route to functions.

For example, assume the following application:

[source,java]
----
@SpringBootApplication
public class DemoFunctionGatewayApplication {

	public static void main(String[] args) {
		SpringApplication.run(DemoFunctionGatewayApplication.class, args);
	}

	
	@Bean
	public Function<String, String> uppercase() {
		return v -> v.toUpperCase();
	}
	
	@Bean
	public Function<String, String> concat() {
		return v -> v + v;
	}
}
----
You can invoke the `concat` or `uppercase` functions by issuing a `GET` or `POST` request to `/concat` or `/uppercase`.

Making a `GET` request to ``http://localhost:8080/uppercase/hello` will invoke the `uppercase` function with the String `hello` and return `HELLO` in the `GET` response body.  

Instead of passing  the function parameter as a path parameter you can use a `POST` request.  For example the following cURL command can issued to invoke the `concat` function:

[source,bash]
----
$ curl -d ‘"hello"' -H "Content-Type: application/json" -X POST http://localhost:8080/concat
----

The response body will contain `hellohello`.

Spring Cloud Gateway also supports function composition by issuing a request to a path composed of function names separated by a comma.  For example:

[source,bash]
----
$ curl -d ‘"hello"' -H "Content-Type: application/json" -X POST http://localhost:8080/concat,uppercase
----

The response body will contain `HELLOHELLO`.