From ccaa19d51f060938980a03501590f9efeb76b6d9 Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Thu, 7 Jul 2016 10:56:33 +0100 Subject: [PATCH] Document how to configure a RestTemplate to use a proxy Closes gh-6331 --- spring-boot-docs/pom.xml | 10 +-- spring-boot-docs/src/main/asciidoc/howto.adoc | 24 +++++++ spring-boot-docs/src/main/asciidoc/index.adoc | 1 + .../main/asciidoc/spring-boot-features.adoc | 16 +++++ ...RestTemplateProxyCustomizationExample.java | 67 +++++++++++++++++++ 5 files changed, 113 insertions(+), 5 deletions(-) create mode 100644 spring-boot-docs/src/main/java/org/springframework/boot/web/client/RestTemplateProxyCustomizationExample.java diff --git a/spring-boot-docs/pom.xml b/spring-boot-docs/pom.xml index ff580e8181..1be05ea19f 100644 --- a/spring-boot-docs/pom.xml +++ b/spring-boot-docs/pom.xml @@ -974,7 +974,7 @@ generate-docbook - generate-resources + prepare-package process-asciidoc @@ -1032,7 +1032,7 @@ generate-html - generate-resources + prepare-package ${basedir}/src/main/docbook/xsl/html-singlepage.xsl ${basedir}/target/docbook/htmlsingle @@ -1058,7 +1058,7 @@ generate-html - generate-resources + prepare-package ${basedir}/src/main/docbook/xsl/html-multipage.xsl ${basedir}/target/docbook/html @@ -1085,7 +1085,7 @@ generate-pdf - generate-resources + prepare-package ${basedir}/src/main/docbook/xsl/pdf.xsl ${basedir}/target/docbook/pdf @@ -1104,7 +1104,7 @@ generate-epub3 - generate-resources + prepare-package ${basedir}/src/main/docbook/xsl/epub.xsl ${basedir}/target/docbook/epub diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc index b22aadb2c5..fb117e1f12 100644 --- a/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -1395,6 +1395,30 @@ have been applied from the auto-configuration: +[[howto-http-clients]] +== HTTP clients + + + +[[howto-http-clients-proxy-configuration]] +=== Configure RestTemplate to use a proxy +As described in <>, +a `RestTemplateCustomizer` can be used with `RestTemplateBuilder` to build a customized +`RestTemplate`. This is the recommended approach for creating a `RestTemplate` configured +to use a proxy. + +The exact details of the proxy configuration depend on the underlying client request +factory that is being used. Here's an example of configuring +`HttpComponentsClientRequestFactory` with an `HttpClient` that uses a proxy for all hosts +except `192.168.0.5`. + +[source,java,indent=0] +---- +include::{code-examples}/web/client/RestTemplateProxyCustomizationExample.java[tag=customizer] +---- + + + [[howto-logging]] == Logging diff --git a/spring-boot-docs/src/main/asciidoc/index.adoc b/spring-boot-docs/src/main/asciidoc/index.adoc index 165f7a656c..09c7fc5b5e 100644 --- a/spring-boot-docs/src/main/asciidoc/index.adoc +++ b/spring-boot-docs/src/main/asciidoc/index.adoc @@ -47,6 +47,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson; :gradle-userguide: http://www.gradle.org/docs/current/userguide :propdeps-plugin: https://github.com/spring-projects/gradle-plugins/tree/master/propdeps-plugin :ant-manual: http://ant.apache.org/manual +:code-examples: ../java/org/springframework/boot // ====================================================================================== include::documentation-overview.adoc[] diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index db6f4e41c1..a81509a40c 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -4302,6 +4302,22 @@ TIP: `RestTemplateBuilder` includes a number of useful methods that can be used configure a `RestTemplate`. For example, to add BASIC auth support you can use `builder.basicAuthorization("user", "password").build()`. +[[boot-features-restclient-customization]] +=== RestTemplate customization +When a `RestTemplateBuilder` builds a `RestTemplate` it can be further customized using +a `RestTemplateCustomizer`. Any `RestTemplateCustomizer` beans will be automatically +added to the auto-configured `RestTemplateBuilder`. Furthermore, a new +`RestTemplateBuilder` with additional customizers can be created by calling +`additionalCustomizers(RestTemplateCustomizer...)`. + +Here's an example of a customizer that configures the use of a proxy for all hosts except +`192.168.0.5`: + +[source,java,indent=0] +---- +include::{code-examples}/web/client/RestTemplateProxyCustomizationExample.java[tag=customizer] +---- + [[boot-features-email]] diff --git a/spring-boot-docs/src/main/java/org/springframework/boot/web/client/RestTemplateProxyCustomizationExample.java b/spring-boot-docs/src/main/java/org/springframework/boot/web/client/RestTemplateProxyCustomizationExample.java new file mode 100644 index 0000000000..157258eebb --- /dev/null +++ b/spring-boot-docs/src/main/java/org/springframework/boot/web/client/RestTemplateProxyCustomizationExample.java @@ -0,0 +1,67 @@ +/* + * Copyright 2012-2016 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.web.client; + +import org.apache.http.HttpException; +import org.apache.http.HttpHost; +import org.apache.http.HttpRequest; +import org.apache.http.client.HttpClient; +import org.apache.http.impl.client.HttpClientBuilder; +import org.apache.http.impl.conn.DefaultProxyRoutePlanner; +import org.apache.http.protocol.HttpContext; + +import org.springframework.http.client.HttpComponentsClientHttpRequestFactory; +import org.springframework.web.client.RestTemplate; + +/** + * Example configuration for using a {@link RestTemplateCustomizer} to configure a proxy. + * + * @author Andy Wilkinson + */ +public class RestTemplateProxyCustomizationExample { + + /** + * A {@link RestTemplateCustomizer} that applies an HttpComponents-based request + * factory that is configured to use a proxy. + */ + // tag::customizer[] + static class ProxyCustomizer implements RestTemplateCustomizer { + + @Override + public void customize(RestTemplate restTemplate) { + HttpHost proxy = new HttpHost("proxy.example.com"); + HttpClient httpClient = HttpClientBuilder.create() + .setRoutePlanner(new DefaultProxyRoutePlanner(proxy) { + + @Override + public HttpHost determineProxy(HttpHost target, + HttpRequest request, HttpContext context) + throws HttpException { + if (target.getHostName().equals("192.168.0.5")) { + return null; + } + return super.determineProxy(target, request, context); + } + + }).build(); + restTemplate.setRequestFactory( + new HttpComponentsClientHttpRequestFactory(httpClient)); + } + + } + // end::customizer[] +}