From 43edd851e25869c4093b878d7d7b34e58c4129ba Mon Sep 17 00:00:00 2001 From: Ryan Baxter Date: Thu, 14 Jun 2018 20:04:49 -0400 Subject: [PATCH] Adds Javadoc to GatewayFilterSpec. --- .../route/builder/GatewayFilterSpec.java | 211 +++++++++++++++++- 1 file changed, 208 insertions(+), 3 deletions(-) diff --git a/spring-cloud-gateway-core/src/main/java/org/springframework/cloud/gateway/route/builder/GatewayFilterSpec.java b/spring-cloud-gateway-core/src/main/java/org/springframework/cloud/gateway/route/builder/GatewayFilterSpec.java index 4a0722fd..5edaf6e2 100644 --- a/spring-cloud-gateway-core/src/main/java/org/springframework/cloud/gateway/route/builder/GatewayFilterSpec.java +++ b/spring-cloud-gateway-core/src/main/java/org/springframework/cloud/gateway/route/builder/GatewayFilterSpec.java @@ -61,6 +61,9 @@ import org.springframework.web.server.ServerWebExchange; import reactor.retry.Repeat; import reactor.retry.Retry; +/** + * Applies specific filters to routes. + */ public class GatewayFilterSpec extends UriSpec { private static final Log log = LogFactory.getLog(GatewayFilterSpec.class); @@ -68,7 +71,12 @@ public class GatewayFilterSpec extends UriSpec { public GatewayFilterSpec(Route.AsyncBuilder routeBuilder, RouteLocatorBuilder.Builder builder) { super(routeBuilder, builder); } - + + /** + * Applies the filter to the route. + * @param gatewayFilter the filter to apply + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec filter(GatewayFilter gatewayFilter) { if (gatewayFilter instanceof Ordered) { this.routeBuilder.filter(gatewayFilter); @@ -77,6 +85,12 @@ public class GatewayFilterSpec extends UriSpec { return this.filter(gatewayFilter, 0); } + /** + * Applies the filter to the route. + * @param gatewayFilter the filter to apply + * @param order the order to apply the filter + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec filter(GatewayFilter gatewayFilter, int order) { if (gatewayFilter instanceof Ordered) { this.routeBuilder.filter(gatewayFilter); @@ -88,33 +102,65 @@ public class GatewayFilterSpec extends UriSpec { return this; } + /** + * Applies the list of filters to the route. + * @param gatewayFilters the filters to apply + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec filters(GatewayFilter... gatewayFilters) { this.routeBuilder.filters(gatewayFilters); return this; } + /** + * Applies the list of filters to the route. + * @param gatewayFilters the filters to apply + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec filters(Collection gatewayFilters) { this.routeBuilder.filters(gatewayFilters); return this; } + /** + * Adds a request header to the request before it is routed by the Gateway. + * @param headerName the header name + * @param headerValue the header value + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec addRequestHeader(String headerName, String headerValue) { return filter(getBean(AddRequestHeaderGatewayFilterFactory.class) .apply(c -> c.setName(headerName).setValue(headerValue))); } + /** + * Adds a request parameter to the request before it is routed by the Gateway. + * @param param the parameter name + * @param value the parameter vaule + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec addRequestParameter(String param, String value) { return filter(getBean(AddRequestParameterGatewayFilterFactory.class) .apply(c -> c.setName(param).setValue(value))); } + /** + * Adds a header to the response returned to the Gateway from the route. + * @param headerName the header name + * @param headerValue the header value + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec addResponseHeader(String headerName, String headerValue) { return filter(getBean(AddResponseHeaderGatewayFilterFactory.class) .apply(c -> c.setName(headerName).setValue(headerValue))); } /** - * Depends on `spring-cloud-starter-netflix-hystrix`, {@see http://cloud.spring.io/spring-cloud-netflix/} + * Wraps the route in a Hystrix command. + * Depends on @{code org.springframework.cloud::spring-cloud-starter-netflix-hystrix} being on the classpath, + * {@see http://cloud.spring.io/spring-cloud-netflix/} + * @param configConsumer a {@link Consumer} which provides configuration for the Hystrix command + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters */ public GatewayFilterSpec hystrix(Consumer configConsumer) { HystrixGatewayFilterFactory factory; @@ -127,59 +173,135 @@ public class GatewayFilterSpec extends UriSpec { return filter(factory.apply(this.routeBuilder.getId(), configConsumer)); } + /** + * A filter that can be used to modify the request body. + * @param inClass the class to convert the incoming request body to + * @param outClass the class the Gateway will add to the request before it is routed + * @param rewriteFunction the {@link RewriteFunction} that transforms the request body + * @param the original request body class + * @param the new request body class + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec modifyRequestBody(Class inClass, Class outClass, RewriteFunction rewriteFunction) { return filter(getBean(ModifyRequestBodyGatewayFilterFactory.class) .apply(c -> c.setRewriteFunction(inClass, outClass, rewriteFunction))); } + /** + * A filter that can be used to modify the response body + * @param inClass the class to conver the response body to + * @param outClass the class the Gateway will add to the response before it is returned to the client + * @param rewriteFunction the {@link RewriteFunction} that transforms the response body + * @param the original response body class + * @param the new response body class + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec modifyResponseBody(Class inClass, Class outClass, RewriteFunction rewriteFunction) { return filter(getBean(ModifyResponseBodyGatewayFilterFactory.class) .apply(c -> c.setRewriteFunction(inClass, outClass, rewriteFunction))); } + /** + * A filter that can be used to add a prefix to the path of a request before it is routed by the Gateway. + * @param prefix the prefix to add to the path + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec prefixPath(String prefix) { return filter(getBean(PrefixPathGatewayFilterFactory.class) .apply(c -> c.setPrefix(prefix))); } + /** + * A filter that will preserve the host header of the request on the outgoing request from the Gateway. + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec preserveHostHeader() { return filter(getBean(PreserveHostHeaderGatewayFilterFactory.class).apply()); } + /** + * A filter that will return a redirect response back to the client. + * @param status an HTTP status code, should be a {@code 300} series redirect + * @param url the URL to redirect to. This URL will be set in the {@code location} header + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec redirect(int status, URI url) { return redirect(String.valueOf(status), url.toString()); } + /** + * A filter that will return a redirect response back to the client. + * @param status an HTTP status code, should be a {@code 300} series redirect + * @param url the URL to redirect to. This URL will be set in the {@code location} header + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec redirect(int status, String url) { return redirect(String.valueOf(status), url); } + /** + * A filter that will return a redirect response back to the client. + * @param status an HTTP status code, should be a {@code 300} series redirect + * @param url the URL to redirect to. This URL will be set in the {@code location} header + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec redirect(String status, URI url) { return redirect(status, url.toString()); } + /** + * A filter that will return a redirect response back to the client. + * @param status an HTTP status code, should be a {@code 300} series redirect + * @param url the URL to redirect to. This URL will be set in the {@code location} header + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec redirect(String status, String url) { return filter(getBean(RedirectToGatewayFilterFactory.class).apply(status, url)); } + /** + * A filter that will return a redirect response back to the client. + * @param status an HTTP status code, should be a {@code 300} series redirect + * @param url the URL to redirect to. This URL will be set in the {@code location} header + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec redirect(HttpStatus status, URL url) { return filter(getBean(RedirectToGatewayFilterFactory.class).apply(status, url)); } + /** + * A filter that will remove a request header before the request is routed by the Gateway. + * @param headerName the name of the header to remove + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec removeRequestHeader(String headerName) { return filter(getBean(RemoveRequestHeaderGatewayFilterFactory.class) .apply(c -> c.setName(headerName))); } + /** + * A filter that will remove a response header before the Gateway returns the response to the client. + * @param headerName the name of the header to remove + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec removeResponseHeader(String headerName) { return filter(getBean(RemoveResponseHeaderGatewayFilterFactory.class) .apply(c -> c.setName(headerName))); } + /** + * A filter that will set up a request rate limiter for a route. + * @param configConsumer a {@link Consumer} that will return configuration for the rate limiter + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec requestRateLimiter(Consumer configConsumer) { return filter(getBean(RequestRateLimiterGatewayFilterFactory.class).apply(configConsumer)); } + /** + * A filter that will set up a request rate limiter for a route. + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public RequestRateLimiterSpec requestRateLimiter() { return new RequestRateLimiterSpec(getBean(RequestRateLimiterGatewayFilterFactory.class)); } @@ -212,76 +334,159 @@ public class GatewayFilterSpec extends UriSpec { } + /** + * A filter which rewrites the request path before it is routed by the Gateway + * @param regex a Java regular expression to match the path against + * @param replacement the replacement for the path + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec rewritePath(String regex, String replacement) { return filter(getBean(RewritePathGatewayFilterFactory.class) .apply(c -> c.setRegexp(regex).setReplacement(replacement))); } /** - * 5xx errors and GET are retryable + * A filter that will retry failed requests. + * By default {@code 5xx} errors and {@code GET}s are retryable. * @param retries max number of retries + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters */ public GatewayFilterSpec retry(int retries) { return filter(getBean(RetryGatewayFilterFactory.class) .apply(retryConfig -> retryConfig.setRetries(retries))); } + /** + * A filter that will retry failed requests. + * @param retryConsumer a {@link Consumer} which returns a {@link org.springframework.cloud.gateway.filter.factory.RetryGatewayFilterFactory.RetryConfig} + * to configure the retry functionality + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec retry(Consumer retryConsumer) { return filter(getBean(RetryGatewayFilterFactory.class).apply(retryConsumer)); } + /** + * A filter that will retry failed requests. + * @param repeat a {@link Repeat} + * @param retry a {@link Retry} + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec retry(Repeat repeat, Retry retry) { return filter(getBean(RetryGatewayFilterFactory.class).apply(repeat, retry)); } + /** + * A filter that adds a number of headers to the response at the reccomendation from + * this blog post. + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ @SuppressWarnings("unchecked") public GatewayFilterSpec secureHeaders() { return filter(getBean(SecureHeadersGatewayFilterFactory.class).apply(c -> {})); } + /** + * A filter that sets the path of the request before it is routed by the Gateway. + * @param template the path to set on the request, allows multiple matching segments using URI templates from + * Spring Framework + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec setPath(String template) { return filter(getBean(SetPathGatewayFilterFactory.class) .apply(c -> c.setTemplate(template))); } + /** + * A filter that sets a header on the request before it is routed by the Gateway. + * @param headerName the header name + * @param headerValue the value of the header + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec setRequestHeader(String headerName, String headerValue) { return filter(getBean(SetRequestHeaderGatewayFilterFactory.class) .apply(c -> c.setName(headerName).setValue(headerValue))); } + /** + * A filter that sets a header on the response before it is returned to the client by the Gateway. + * @param headerName the header name + * @param headerValue the value of the header + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec setResponseHeader(String headerName, String headerValue) { return filter(getBean(SetResponseHeaderGatewayFilterFactory.class) .apply(c -> c.setName(headerName).setValue(headerValue))); } + /** + * A filter that sets the status on the response before it is returned to the client by the Gateway. + * @param status the status to set on the response + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec setStatus(int status) { return setStatus(String.valueOf(status)); } + /** + * A filter that sets the status on the response before it is returned to the client by the Gateway. + * @param status the status to set on the response + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec setStatus(HttpStatus status) { return setStatus(status.toString()); } + /** + * A filter that sets the status on the response before it is returned to the client by the Gateway. + * @param status the status to set on the response + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec setStatus(String status) { return filter(getBean(SetStatusGatewayFilterFactory.class) .apply(c -> c.setStatus(status))); } + /** + * A filter which forces a {@code WebSession::save} operation before forwarding the call downstream. This is of + * particular use when using something like Spring Session + * with a lazy data store and need to ensure the session state has been saved before making the forwarded call. + * If you are integrating Spring Security with + * Spring Session, and want to ensure security details have been forwarded to the remote process, this is critical. + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ @SuppressWarnings("unchecked") public GatewayFilterSpec saveSession() { return filter(getBean(SaveSessionGatewayFilterFactory.class).apply(c -> {})); } + /** + * Strips the prefix from the path of the request before it is routed by the Gateway. + * @param parts the number of parts of the path to remove + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec stripPrefix(int parts) { return filter(getBean(StripPrefixGatewayFilterFactory.class) .apply(c -> c.setParts(parts))); } + /** + * A filter which changes the URI the request will be routed to by the Gateway by pulling it from a header on the + * request. + * @param headerName the header name containing the URI + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec requestHeaderToRequestUri(String headerName) { return filter(getBean(RequestHeaderToRequestUriGatewayFilterFactory.class) .apply(c -> c.setName(headerName))); } + /** + * A filter which change the URI the request will be routed to by the Gateway. + * @param determineRequestUri a {@link Function} which takes a {@link ServerWebExchange} and returns a URI to + * route the request to + * @return a {@link GatewayFilterSpec} that can be used to apply additional filters + */ public GatewayFilterSpec changeRequestUri( Function> determineRequestUri) { return filter(