Added docs for custom async rest template (#566)

fixes #564

docs/src/main/asciidoc/spring-cloud-sleuth.adoc

@@ -681,6 +681,16 @@ To block the `AsyncRestTemplate` features set `spring.sleuth.web.async.client.en
 To disable creation of the default `TraceAsyncClientHttpRequestFactoryWrapper` set `spring.sleuth.web.async.client.factory.enabled`
 to `false`. If you don't want to create `AsyncRestClient` at all set `spring.sleuth.web.async.client.template.enabled` to `false`.
 
+===== Multiple Asynchronous Rest Templates
+
+Sometimes you need to use multiple implementations of Asynchronous Rest Template. In the following snippet you
+can see an example of how to set up such a custom `AsyncRestTemplate`.
+
+[source,java]
+----
+include::../../../../spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/async/MultipleAsyncRestTemplateTests.java[tags=custom_async_rest_template,indent=0]
+----
+
 === Feign
 
 By default Spring Cloud Sleuth provides integration with feign via the `TraceFeignClientAutoConfiguration`. You can disable it entirely

spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/async/MultipleAsyncRestTemplateTests.java

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2013-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.cloud.sleuth.instrument.async;
+
+import java.io.IOException;
+import java.net.URI;
+import java.util.concurrent.Executor;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.cloud.sleuth.SpanInjector;
+import org.springframework.cloud.sleuth.Tracer;
+import org.springframework.cloud.sleuth.instrument.web.HttpTraceKeysInjector;
+import org.springframework.cloud.sleuth.instrument.web.client.TraceAsyncClientHttpRequestFactoryWrapper;
+import org.springframework.cloud.sleuth.instrument.web.client.TraceAsyncRestTemplate;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.HttpRequest;
+import org.springframework.http.client.AsyncClientHttpRequest;
+import org.springframework.http.client.AsyncClientHttpRequestFactory;
+import org.springframework.http.client.ClientHttpRequest;
+import org.springframework.http.client.ClientHttpRequestFactory;
+import org.springframework.test.context.junit4.SpringRunner;
+import org.springframework.web.client.AsyncRestTemplate;
+
+import static org.assertj.core.api.BDDAssertions.then;
+
+/**
+ * @author Marcin Grzejszczak
+ */
+@RunWith(SpringRunner.class)
+@SpringBootTest(classes = MultipleAsyncRestTemplateTests.Config.class,
+		webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+public class MultipleAsyncRestTemplateTests {
+
+	@Autowired @Qualifier("customAsyncRestTemplate") AsyncRestTemplate asyncRestTemplate;
+
+	@Test
+	public void should_start_context_with_custom_async_client() throws Exception {
+		then(this.asyncRestTemplate).isNotNull();
+	}
+
+	//tag::custom_async_rest_template[]
+	@Configuration
+	@EnableAutoConfiguration
+	static class Config {
+		@Autowired Tracer tracer;
+		@Autowired HttpTraceKeysInjector httpTraceKeysInjector;
+		@Autowired SpanInjector<HttpRequest> spanInjector;
+
+		@Bean(name = "customAsyncRestTemplate")
+		public AsyncRestTemplate traceAsyncRestTemplate(@Qualifier("customHttpRequestFactoryWrapper")
+				TraceAsyncClientHttpRequestFactoryWrapper wrapper) {
+			return new TraceAsyncRestTemplate(wrapper, this.tracer);
+		}
+
+		@Bean(name = "customHttpRequestFactoryWrapper")
+		public TraceAsyncClientHttpRequestFactoryWrapper traceAsyncClientHttpRequestFactory() {
+			return new TraceAsyncClientHttpRequestFactoryWrapper(this.tracer,
+					this.spanInjector,
+					asyncClientFactory(),
+					clientHttpRequestFactory(),
+					this.httpTraceKeysInjector);
+		}
+
+		private ClientHttpRequestFactory clientHttpRequestFactory() {
+			ClientHttpRequestFactory clientHttpRequestFactory = new CustomClientHttpRequestFactory();
+			//CUSTOMIZE HERE
+			return clientHttpRequestFactory;
+		}
+
+		private AsyncClientHttpRequestFactory asyncClientFactory() {
+			AsyncClientHttpRequestFactory factory = new CustomAsyncClientHttpRequestFactory();
+			//CUSTOMIZE HERE
+			return factory;
+		}
+	}
+	//end::custom_async_rest_template[]
+}
+
+class CustomClientHttpRequestFactory implements ClientHttpRequestFactory {
+
+	@Override public ClientHttpRequest createRequest(URI uri, HttpMethod httpMethod)
+			throws IOException {
+		return null;
+	}
+}
+
+class CustomAsyncClientHttpRequestFactory implements AsyncClientHttpRequestFactory {
+
+	@Override
+	public AsyncClientHttpRequest createAsyncRequest(URI uri, HttpMethod httpMethod)
+			throws IOException {
+		return null;
+	}
+}
+
+class YourCustomThreadPoolTaskExecutor implements Executor {
+
+	@Override public void execute(Runnable command) {
+
+	}
+}