Adds TracingCustomizer and HttpTracingCustomizer

brave/src/main/java/brave/TracingCustomizer.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2013-2019 The OpenZipkin 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 brave;
+
+import brave.handler.FinishedSpanHandler;
+import zipkin2.reporter.Reporter;
+
+/**
+ * This allows configuration plugins to collaborate on building an instance of {@link Tracing}.
+ *
+ * <p>Notably, this decouples framework-level configuration (such as {@link
+ * Tracing.Builder#spanReporter(Reporter)}) from site-specific configuration (such as {@link
+ * Tracing.Builder#addFinishedSpanHandler(FinishedSpanHandler) additional finished span handlers}.
+ *
+ * <h3>Integration examples</h3>
+ *
+ * <p>In practice, a dependency injection tool applies a collection of these instances prior to
+ * {@link Tracing.Builder#build() building the tracing instance}. For example, an injected {@code
+ * List<TracingCustomizer>} parameter to a provider of {@link Tracing}.
+ *
+ * <p>Here are some examples, in alphabetical order:
+ * <pre><ul>
+ *   <li><a href="https://dagger.dev/multibindings.html">Dagger Set Multibindings</a></li>
+ *   <li><a href="http://google.github.io/guice/api-docs/latest/javadoc/com/google/inject/multibindings/Multibinder.html">Guice Set Multibinder</a></li>
+ *   <li><a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-autowired-annotation">Spring Autowired Collections</a></li>
+ * </ul></pre>
+ *
+ * @since 5.7
+ */
+public interface TracingCustomizer {
+  void customize(Tracing.Builder builder);
+}

instrumentation/http/src/main/java/brave/http/HttpTracingCustomizer.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2013-2019 The OpenZipkin 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 brave.http;
+
+import brave.Tracing;
+import brave.TracingCustomizer;
+
+/**
+ * This allows configuration plugins to collaborate on building an instance of {@link HttpTracing}.
+ *
+ * <p>Notably, this decouples framework-level configuration (such as {@link
+ * HttpTracing.Builder#Builder(Tracing) the http tracing instance}) from site-specific configuration
+ * (such as {@link HttpTracing.Builder#clientParser(HttpClientParser) parsers}).
+ *
+ * <p>This also allows one object to customize both {@link Tracing}, via {@link TracingCustomizer},
+ * and the http layer {@link HttpTracing}, by implementing both customizer interfaces.
+ *
+ * <h3>Integration examples</h3>
+ *
+ * <p>In practice, a dependency injection tool applies a collection of these instances prior to
+ * {@link HttpTracing.Builder#build() building the tracing instance}. For example, an injected
+ * {@code List<HttpTracingCustomizer>} parameter to a provider of {@link HttpTracing}.
+ *
+ * <p>Here are some examples, in alphabetical order:
+ * <pre><ul>
+ *   <li><a href="https://dagger.dev/multibindings.html">Dagger Set Multibindings</a></li>
+ *   <li><a href="http://google.github.io/guice/api-docs/latest/javadoc/com/google/inject/multibindings/Multibinder.html">Guice Set Multibinder</a></li>
+ *   <li><a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-autowired-annotation">Spring Autowired Collections</a></li>
+ * </ul></pre>
+ *
+ * @see TracingCustomizer
+ * @since 5.7
+ */
+public interface HttpTracingCustomizer {
+  void customize(HttpTracing.Builder builder);
+}