Document how to configure a RestTemplate to use a proxy

Closes gh-6331

spring-boot-docs/pom.xml

@@ -974,7 +974,7 @@
 						<executions>
 							<execution>
 								<id>generate-docbook</id>
-								<phase>generate-resources</phase>
+								<phase>prepare-package</phase>
 								<goals>
 									<goal>process-asciidoc</goal>
 								</goals>
@@ -1032,7 +1032,7 @@
 								<goals>
 									<goal>generate-html</goal>
 								</goals>
-								<phase>generate-resources</phase>
+								<phase>prepare-package</phase>
 								<configuration>
 									<htmlCustomization>${basedir}/src/main/docbook/xsl/html-singlepage.xsl</htmlCustomization>
 									<targetDirectory>${basedir}/target/docbook/htmlsingle</targetDirectory>
@@ -1058,7 +1058,7 @@
 								<goals>
 									<goal>generate-html</goal>
 								</goals>
-								<phase>generate-resources</phase>
+								<phase>prepare-package</phase>
 								<configuration>
 									<htmlCustomization>${basedir}/src/main/docbook/xsl/html-multipage.xsl</htmlCustomization>
 									<targetDirectory>${basedir}/target/docbook/html</targetDirectory>
@@ -1085,7 +1085,7 @@
 								<goals>
 									<goal>generate-pdf</goal>
 								</goals>
-								<phase>generate-resources</phase>
+								<phase>prepare-package</phase>
 								<configuration>
 									<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
 									<targetDirectory>${basedir}/target/docbook/pdf</targetDirectory>
@@ -1104,7 +1104,7 @@
 								<goals>
 									<goal>generate-epub3</goal>
 								</goals>
-								<phase>generate-resources</phase>
+								<phase>prepare-package</phase>
 								<configuration>
 									<epubCustomization>${basedir}/src/main/docbook/xsl/epub.xsl</epubCustomization>
 									<targetDirectory>${basedir}/target/docbook/epub</targetDirectory>

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 <<spring-boot-features.adoc#boot-features-restclient-customization>>,
+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
 

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[]

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]]

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[]
+}