cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dk...@apache.org
Subject svn commit: r1018013 [4/6] - in /websites/production/cxf/content: ./ cache/ docs/ docs/using-opentracing.data/
Date Mon, 11 Sep 2017 19:56:30 GMT
Modified: websites/production/cxf/content/docs/swagger2feature.html
==============================================================================
--- websites/production/cxf/content/docs/swagger2feature.html (original)
+++ websites/production/cxf/content/docs/swagger2feature.html Mon Sep 11 19:56:29 2017
@@ -118,16 +118,16 @@ Apache CXF -- Swagger2Feature
            <!-- Content -->
            <div class="wiki-content">
 <div id="ConfluenceContent"><h1 id="Swagger2Feature-Swagger2Feature">Swagger2Feature</h1><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1504004877808 {padding: 0px;}
-div.rbtoc1504004877808 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1504004877808 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505159704987 {padding: 0px;}
+div.rbtoc1505159704987 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505159704987 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1504004877808">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505159704987">
 <ul class="toc-indentation"><li><a shape="rect" href="#Swagger2Feature-Swagger2Feature">Swagger2Feature</a></li><li><a shape="rect" href="#Swagger2Feature-Setup">Setup</a></li><li><a shape="rect" href="#Swagger2Feature-Properties">Properties</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringfromCode">Configuring from Code</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinSpring">Configuring in Spring</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinBlueprint">Configuring in Blueprint</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</a></li><li><a shape="rect" href="#Swagger2Feature-New:ConfiguringfromPropertiesfile">New: Configuring from Properties file</a></li><li><a shape="rect" href="#Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</a></li><li><a shape="rect" href="#Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger Documents</a></li><l
 i><a shape="rect" href="#Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</a>
 <ul class="toc-indentation"><li><a shape="rect" href="#Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</a></li><li><a shape="rect" href="#Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</a></li></ul>
-</li><li><a shape="rect" href="#Swagger2Feature-Samples">Samples</a></li></ul>
+</li><li><a shape="rect" href="#Swagger2Feature-ReverseProxy">Reverse Proxy</a></li><li><a shape="rect" href="#Swagger2Feature-SetaCXFServletinitparameter'use-x-forwarded-headers'to'true'ifyouaccessSwaggerJSONand/o">Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/o</a></li><li><a shape="rect" href="#Swagger2Feature-Samples">Samples</a></li></ul>
 </div><p>&#160;</p><p>The CXF Swagger2Feature allows you to generate&#160;<a shape="rect" class="external-link" href="http://swagger.io/specification/" rel="nofollow">Swagger 2.0</a>&#160;documents from JAX-RS service endpoints with a simple configuration.</p><p>For generating <a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md" rel="nofollow">Swagger 1.2</a> documents, you can use SwaggerFeature instead of Swagger2Feature (for CXF versions &lt;= 3.1.x).</p><p>These features can be configured programatically in Java or using Spring or Blueprint beans.</p><h1 id="Swagger2Feature-Setup">Setup</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;dependency&gt;
+<pre class="brush: xml; gutter: false; theme: Confluence" style="font-size:12px;">&lt;dependency&gt;
     &lt;groupId&gt;org.apache.cxf&lt;/groupId&gt;
     &lt;artifactId&gt;cxf-rt-rs-service-description-swagger&lt;/artifactId&gt;
     &lt;version&gt;3.1.11&lt;/version&gt;
@@ -135,7 +135,7 @@ div.rbtoc1504004877808 li {margin-left:
 
 </pre>
 </div></div><p>Note that a <strong>cxf-rt-rs-service-description</strong> needs to be used if older CXF 3.1.x versions are used.</p><p>&#160;</p><h1 id="Swagger2Feature-Properties">Properties</h1><p><span style="line-height: 1.4285715;">The following optional parameters can be configured in Swagger2Feature</span></p><p><span style="line-height: 1.4285715;">Note some properties listed below are not available or used differently in SwaggerFeature, as the corresponding properties are used differently in Swagger 2.0 and Swagger 1.2. Please refer to the corresponding Swagger documentation for more information.)</span></p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Name</th><th colspan="1" rowspan="1" class="confluenceTh">Description</th><th colspan="1" rowspan="1" class="confluenceTh">Default</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">basePath</td><td colspan="1" rowspan="1" class="confluenceTd">the
  context root path<sup>+</sup></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contact</td><td colspan="1" rowspan="1" class="confluenceTd">the contact information<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"users@cxf.apache.org"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">description</td><td colspan="1" rowspan="1" class="confluenceTd">the description<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"The Application"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">filterClass</td><td colspan="1" rowspan="1" class="confluenceTd">a security filter<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">host</td><td colspan="1" rowspan="1" class="confluenceTd">the host and port<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td
  colspan="1" rowspan="1" class="confluenceTd">ignoreRoutes</td><td colspan="1" rowspan="1" class="confluenceTd">excludes specific paths when scanning all resources (see scanAllResources)<span>+</span><span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">license</td><td colspan="1" rowspan="1" class="confluenceTd">the license<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"Apache 2.0 License"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">licenceUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the license URL<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"<span class="nolink">http://www.apache.org/licenses/LICENSE-2.0.html</span>"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">prettyPrint</td><td colspan="1" rowspan="1" class="confluenceTd">when generating swagger.json, pretty-print the json document<span>+</span></td><td cols
 pan="1" rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">resourcePackage</td><td colspan="1" rowspan="1" class="confluenceTd">a list of comma separated package names where resources must be scanned<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">a list of service classes configured at the endpoint</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">runAsFilter</td><td colspan="1" rowspan="1" class="confluenceTd">runs the feature as a filter</td><td colspan="1" rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scan</td><td colspan="1" rowspan="1" class="confluenceTd">generates the swagger documentation<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">true</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scanAllResources</td><td colspan="1" rowspan="1" class="confluenceTd">scans all resources including non-annotated JAX-RS r
 esources<span>+</span><span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">schemes</td><td colspan="1" rowspan="1" class="confluenceTd">the protocol schemes<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">termsOfServiceUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the terms of service URL<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">title</td><td colspan="1" rowspan="1" class="confluenceTd">the title<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"Sample REST Application"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">version</td><td colspan="1" rowspan="1" class="confluenceTd">the version<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"1.0.0"</td></tr></tbody></ta
 ble></div><p>Note: those descriptions marked with&#160;<span>+ correspond to the properties defined in Swagger's BeanConfig, and those marked with&#160;<span>+</span><span>+ correspond to&#160;the properties defined in Swagger's ReaderConfig.</span></span></p><h1 id="Swagger2Feature-ConfiguringfromCode">Configuring from Code</h1><p>&#160;</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">import org.apache.cxf.frontend.ServerFactoryBean;
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">import org.apache.cxf.frontend.ServerFactoryBean;
 import org.apache.cxf.jaxrs.swagger.Swagger2Feature;
 ...
 
@@ -148,7 +148,7 @@ import org.apache.cxf.jaxrs.swagger.Swag
    	ServerFactoryBean sfb = new ServerFactoryBean();
    	sfb.getFeatures().add(feature);</pre>
 </div></div><p>&#160;</p><h1 id="Swagger2Feature-ConfiguringinSpring">Configuring in Spring</h1><p>&#160;</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;beans xmlns="http://www.springframework.org/schema/beans"
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">&lt;beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://cxf.apache.org/core"
        xmlns:jaxrs="http://cxf.apache.org/jaxrs"
        xsi:schemaLocation="http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd
@@ -183,7 +183,7 @@ import org.apache.cxf.jaxrs.swagger.Swag
 
 </pre>
 </div></div><p>&#160;</p><h1 id="Swagger2Feature-ConfiguringinBlueprint">Configuring in Blueprint</h1><p>&#160;</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">&lt;blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:cxf="http://cxf.apache.org/blueprint/core"
        xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
@@ -219,7 +219,7 @@ import org.apache.cxf.jaxrs.swagger.Swag
 &lt;/blueprint&gt;
 &#160;</pre>
 </div></div><h1 id="Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</h1><p>&#160;</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;web-app&gt;
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">&lt;web-app&gt;
     &lt;context-param&gt;
         &lt;param-name&gt;contextParam&lt;/param-name&gt;
         &lt;param-value&gt;contextParamValue&lt;/param-value&gt;
@@ -252,15 +252,15 @@ import org.apache.cxf.jaxrs.swagger.Swag
     &lt;/servlet-mapping&gt;
     
 &lt;/web-app&gt;</pre>
-</div></div><h1 id="Swagger2Feature-New:ConfiguringfromPropertiesfile">New: Configuring from Properties file</h1><p>Starting from CXF 3.1.13 and 3.2.0 it is possible to configure Swagger2Feature with a Properties file.</p><p>For example, while a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> demo configures the feature <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot/src/main/java/sample/rs/service/SampleRestApplication.java#L54" rel="nofollow">from the code</a>, a &#160;<a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a> demo has it configured from <a shape="rect" class="external-link" href="https://gith
 ub.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/swagger.properties" rel="nofollow">the properties file</a>.</p><p>Default location for a properties file is "<strong>/swagger.properties</strong>". Swagger2Feature will pick it up if it is available, and the location can be overridden with a new Swagger2Feature '<strong>swaggerPropertiesLocation</strong>' property.&#160;</p><p>Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.</p><h1 id="Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</h1><p>See <a shape="rect" class="external-link" href="https://github.com/apache/
 cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and on how to create Swagger2Feature in a @Bean method and&#160;<a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a> on how to auto-enable it.</p><p>&#160;</p><h1 id="Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger Documents</h1><p>When Swagger is enabled by Swagger feature, the Swagger documents will be available at the location URL constructed of the service endpoint location followed by /swagger.json or /swagger.yaml.</p><p>For example, lets assume a JAX-RS endpoint is published at 'http://host:port/context/services/' where 'context' is a web application context,&#160; "/services" is a servlet URL. In this case its Swagger documents are available at 'http://host:port/context/services/swagger.json' and 'ht
 tp://host:port/context/services/swagger.yaml'.</p><p>Starting from CXF 3.1.7 the CXF Services page will link to Swagger documents if Swagger2Feature is active.&#160;</p><p>In the above example, go to&#160;'<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger JSON document.</p><p>If <a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/README.md#cors-support" rel="nofollow">CORS support</a> is needed to access the definition from a Swagger UI on another host, the <a shape="rect" href="jax-rs-cors.html">CrossOriginResourceSharingFilter from cxf-rt-rs-security-cors</a> can be added.</p><h1 id="Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>First one needs to add the following</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;dependency&gt;
+</div></div><h1 id="Swagger2Feature-New:ConfiguringfromPropertiesfile">New: Configuring from Properties file</h1><p>Starting from CXF 3.1.13 and 3.2.0 it is possible to configure Swagger2Feature with a Properties file.</p><p>For example, while a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> demo configures the feature <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot/src/main/java/sample/rs/service/SampleRestApplication.java#L54" rel="nofollow">from the code</a>, a &#160;<a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a> demo has it configured from <a shape="rect" class="external-link" href="https://gith
 ub.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/swagger.properties" rel="nofollow">the properties file</a>.</p><p>Default location for a properties file is "<strong>/swagger.properties</strong>". Swagger2Feature will pick it up if it is available, and the location can be overridden with a new Swagger2Feature '<strong>swaggerPropertiesLocation</strong>' property.&#160;</p><p>Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.</p><h1 id="Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</h1><p>See <a shape="rect" class="external-link" href="https://github.com/apache/
 cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and on how to create Swagger2Feature in a @Bean method and&#160;<a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a> on how to auto-enable it.</p><p>&#160;</p><h1 id="Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger Documents</h1><p>When Swagger is enabled by Swagger feature, the Swagger documents will be available at the location URL constructed of the service endpoint location followed by /swagger.json or /swagger.yaml.</p><p>For example, lets assume a JAX-RS endpoint is published at 'http://host:port/context/services/' where 'context' is a web application context,&#160; "/services" is a servlet URL. In this case its Swagger documents are available at 'http://host:port/context/services/swagger.json' and 'ht
 tp://host:port/context/services/swagger.yaml'.</p><p>Starting from CXF 3.1.7 the CXF Services page will link to Swagger documents if Swagger2Feature is active.&#160;</p><p>In the above example, go to&#160;'<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger JSON document.</p><p>If <a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/README.md#cors-support" rel="nofollow">CORS support</a> is needed to access the definition from a Swagger UI on another host, the <a shape="rect" href="jax-rs-cors.html">CrossOriginResourceSharingFilter from cxf-rt-rs-security-cors</a> can be added.</p><p>&#160;</p><h1 id="Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>First one needs to add the following</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Confluence" style="font-size:12px;">&lt;dependency&gt;
     &lt;groupId&gt;org.webjars&lt;/groupId&gt;
     &lt;artifactId&gt;swagger-ui&lt;/artifactId&gt;
     &lt;version&gt;2.2.10-1&lt;/version&gt;
 &lt;/dependency&gt;
 
 </pre>
-</div></div><p>The newest version 3.x of swagger-ui can also be used.</p><h2 id="Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</h2><p>This feature is available starting from CXF 3.1.7: Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><p>For example, lets assume a JAX-RS endpoint is published at '<span>http://host:port/context/services/</span>'.</p><p>Open the browser and go to '<span>http://host:port/context/services/</span>api-docs?/url=/swagger.json' which will return a Swagger UI page.</p><p>CXF Services page will also link to Swagger UI. Go to&#160;'<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>,&#1
 60;<a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a>&#160;</p><p>Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.</p><h2 id="Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</h2><p>Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder was the only option. It is demoed in <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/mas
 ter/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>.</p><p>In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section</p><h1 id="Swagger2Feature-Samples">Samples</h1><p><span>CXF's distribution contains the following samples.</span></p><ul><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger" rel="nofollow">samples/jax_rs/description_swagger</a>: Swagger 1.2 sample using SwaggerFeature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master
 /distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>:&#160;Swagger 2.0 standalone sample using Swagger2Feature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a>:&#160;Swagger 2.0 standalone sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>:&#160;Swagger 2.0 web application sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/des
 cription_swagger2_osgi</a>:&#160;Swagger 2.0 OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br clear="none"></li></ul><p>&#160;</p></div>
+</div></div><p>The newest version 3.x of swagger-ui can also be used.</p><h2 id="Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</h2><p>This feature is available starting from CXF 3.1.7: Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><p>For example, lets assume a JAX-RS endpoint is published at '<span>http://host:port/context/services/</span>'.</p><p>Open the browser and go to '<span>http://host:port/context/services/</span>api-docs?/url=/swagger.json' which will return a Swagger UI page.</p><p>CXF Services page will also link to Swagger UI. Go to&#160;'<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>,&#1
 60;<a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a>&#160;</p><p>Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.</p><h2 id="Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</h2><p>Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder was the only option. It is demoed in <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/mas
 ter/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>.</p><p>In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section</p><h1 id="Swagger2Feature-ReverseProxy">Reverse Proxy</h1><p>Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/or UI via the reverse proxy. If you use CXF SpringBoot starters then this property is prefixed with a "cxf.servlet.init.", "cxf.servlet.init.use-x-forwarded-headers".</p><p>You may also need to set Swagger2Feature 'usePathBasedConfig' property to 'true' to prevent Swagger from caching the 'basePath' value.</p><h1 id="Sw
 agger2Feature-SetaCXFServletinitparameter'use-x-forwarded-headers'to'true'ifyouaccessSwaggerJSONand/o">Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/o</h1><h1 id="Swagger2Feature-Samples">Samples</h1><p><span>CXF's distribution contains the following samples.</span></p><ul><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger" rel="nofollow">samples/jax_rs/description_swagger</a>: Swagger 1.2 sample using SwaggerFeature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>:&#160;Swagger 2.0 standalone sample using Swagger2Feature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/ma
 in/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a>:&#160;Swagger 2.0 standalone sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>:&#160;Swagger 2.0 web application sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>:&#160;Swagger 2.0 OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br clear="none"></li></ul><p>&#160;</p></div>
            </div>
            <!-- Content -->
          </td>

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-12:41:7.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-12:41:7.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-13:18:20.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-13:18:20.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:10:40.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:10:40.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:19:1.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:19:1.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:26:23.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:26:23.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:37:31.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:37:31.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:40:20.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:40:20.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:46:4.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:46:4.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:49:4.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:49:4.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:50:2.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:50:2.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:54:2.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:54:2.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:55:0.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:55:0.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:58:53.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:58:53.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:9:7.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-14:9:7.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-15:0:49.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/cxf/content/docs/using-opentracing.data/image2017-9-10-15:0:49.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: websites/production/cxf/content/docs/using-opentracing.html
==============================================================================
--- websites/production/cxf/content/docs/using-opentracing.html (added)
+++ websites/production/cxf/content/docs/using-opentracing.html Mon Sep 11 19:56:29 2017
@@ -0,0 +1,395 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You 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.
+-->
+<html>
+  <head>
+
+<link type="text/css" rel="stylesheet" href="/resources/site.css">
+<script src='/resources/space.js'></script>
+
+<meta http-equiv="Content-type" content="text/html;charset=UTF-8">
+<meta name="keywords" content="business integration, EAI, SOA, Service Oriented Architecture, web services, SOAP, JBI, JMS, WSDL, XML, EDI, Electronic Data Interchange, standards support, integration standards, application integration, middleware, software, solutions, services, CXF, open source">
+<meta name="description" content="Apache CXF, Services Framework - Using OpenTracing">
+
+
+<link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shCoreCXF.css">
+<link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shThemeCXF.css">
+
+<script src='/resources/highlighter/scripts/shCore.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
+<script>
+  SyntaxHighlighter.defaults['toolbar'] = false;
+  SyntaxHighlighter.all();
+</script>
+
+
+    <title>
+Apache CXF -- Using OpenTracing
+    </title>
+  </head>
+<body onload="init()">
+
+
+<table width="100%" cellpadding="0" cellspacing="0">
+  <tr>
+    <td id="cell-0-0" colspan="2">&nbsp;</td>
+    <td id="cell-0-1">&nbsp;</td>
+    <td id="cell-0-2" colspan="2">&nbsp;</td>
+  </tr>
+  <tr>
+    <td id="cell-1-0">&nbsp;</td>
+    <td id="cell-1-1">&nbsp;</td>
+    <td id="cell-1-2">
+      <!-- Banner -->
+<div class="banner" id="banner"><div><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td align="left" colspan="1" nowrap>
+<a shape="rect" href="http://cxf.apache.org/" title="Apache CXF"><span style="font-weight: bold; font-size: 170%; color: white">Apache CXF</span></a>
+</td><td align="right" colspan="1" nowrap>
+<a shape="rect" href="http://www.apache.org/" title="The Apache Sofware Foundation"><img border="0" alt="ASF Logo" src="http://cxf.apache.org/images/asf-logo.png"></a>
+</td></tr></table></div></div>
+      <!-- Banner -->
+      <div id="top-menu">
+        <table border="0" cellpadding="1" cellspacing="0" width="100%">
+          <tr>
+            <td>
+              <div align="left">
+                <!-- Breadcrumbs -->
+<a href="index.html">Index</a>&nbsp;&gt;&nbsp;<a href="distributed-tracing.html">Distributed Tracing</a>&nbsp;&gt;&nbsp;<a href="using-opentracing.html">Using OpenTracing</a>
+                <!-- Breadcrumbs -->
+              </div>
+            </td>
+            <td>
+              <div align="right">
+                <!-- Quicklinks -->
+<div id="quicklinks"><p><a shape="rect" href="http://cxf.apache.org/download.html">Download</a> | <a shape="rect" href="http://cxf.apache.org/docs/index.html">Documentation</a></p></div>
+                <!-- Quicklinks -->
+              </div>
+            </td>
+          </tr>
+        </table>
+      </div>
+    </td>
+    <td id="cell-1-3">&nbsp;</td>
+    <td id="cell-1-4">&nbsp;</td>
+  </tr>
+  <tr>
+    <td id="cell-2-0" colspan="2">&nbsp;</td>
+    <td id="cell-2-1">
+      <table>
+        <tr valign="top">
+          <td height="100%">
+            <div id="wrapper-menu-page-right">
+              <div id="wrapper-menu-page-top">
+                <div id="wrapper-menu-page-bottom">
+                  <div id="menu-page">
+                    <!-- NavigationBar -->
+<div id="navigation"><ul class="alternate"><li><a shape="rect" href="overview.html">Overview</a></li><li><a shape="rect" href="how-tos.html">How-Tos</a></li><li><a shape="rect" href="frontends.html">Frontends</a></li><li><a shape="rect" href="databindings.html">DataBindings</a></li><li><a shape="rect" href="transports.html">Transports</a></li><li><a shape="rect" href="configuration.html">Configuration</a></li><li><a shape="rect" href="debugging-and-logging.html">Debugging and Logging</a></li><li><a shape="rect" href="tools.html">Tools</a></li><li><a shape="rect" href="restful-services.html">RESTful Services</a></li><li><a shape="rect" href="wsdl-bindings.html">WSDL Bindings</a></li><li><a shape="rect" href="service-routing.html">Service Routing</a></li><li><a shape="rect" href="dynamic-languages.html">Dynamic Languages</a></li><li><a shape="rect" href="ws-support.html">WS-* Support</a></li><li><a shape="rect" href="advanced-integration.html">Advanced Integration</a></li><li><a shape
 ="rect" href="deployment.html">Deployment</a></li><li><a shape="rect" href="schemas-and-namespaces.html">Use of Schemas and Namespaces</a></li></ul><hr><ul class="alternate"><li><p>Search</p></li></ul><form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse">
+  <div>
+    <input type="hidden" name="cx" value="002890367768291051730:o99qiwa09y4">
+    <input type="hidden" name="ie" value="UTF-8">
+    <input type="text" name="q" size="21">
+    <input type="submit" name="sa" value="Search">
+  </div>
+</form>
+<script type="text/javascript" src="http://www.google.com/cse/brand?form=cse-search-box&amp;lang=en"></script><hr><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest/">API 3.1.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.0.x/">API 3.0.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/">CXF Website</a></li></ul></div>
+                    <!-- NavigationBar -->
+                  </div>
+              </div>
+            </div>
+          </div>
+         </td>
+         <td height="100%">
+           <!-- Content -->
+           <div class="wiki-content">
+<div id="ConfluenceContent"><h1 id="UsingOpenTracing-/*&lt;![CDATA[*/div.rbtoc1505159711790{padding:0px;}div.rbtoc1505159711790ul{list-style:disc;margin-left:0px;}div.rbtoc1505159711790li{margin-left:0px;padding-left:0px;}/*]]&gt;*/#UsingOpenTracing-Overview#UsingOpenTracing-OverviewDistributedTr"><style type="text/css">/*<![CDATA[*/
+div.rbtoc1505159711790 {padding: 0px;}
+div.rbtoc1505159711790 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505159711790 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></h1><div class="toc-macro rbtoc1505159711790">
+<ul class="toc-indentation"><li><a shape="rect" href="#UsingOpenTracing-"></a></li><li><a shape="rect" href="#UsingOpenTracing-Overview">Overview</a></li><li><a shape="rect" href="#UsingOpenTracing-DistributedTracinginApacheCXFusingOpenTracing">Distributed Tracing in Apache CXF using OpenTracing</a></li><li><a shape="rect" href="#UsingOpenTracing-ConfiguringClient">Configuring Client</a></li><li><a shape="rect" href="#UsingOpenTracing-ConfiguringServer">Configuring Server</a></li><li><a shape="rect" href="#UsingOpenTracing-DistributedTracingInAction:UsageScenarios">Distributed Tracing In Action: Usage Scenarios</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#UsingOpenTracing-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example #1: Client and Server with default distributed tracing configured</a></li><li><a shape="rect" href="#UsingOpenTracing-Example#2:ClientandServerwithnestedtrace">Example #2: Client and Server with nested trace</a></li><li><a shape="rect" href="#UsingOpenTracing-Example#3:ClientandServertracewithtimeline">Example #3: Client and Server trace with timeline</a></li><li><a shape="rect" href="#UsingOpenTracing-Example#4:ClientandServerwithbinaryannotations(key/value)">Example #4: Client and Server with binary annotations (key/value)</a></li><li><a shape="rect" href="#UsingOpenTracing-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example #5: Client and Server with parallel trace (involving thread pools)</a></li><li><a shape="rect" href="#UsingOpenTracing-Example#6:ClientandServerwithasynchronousJAX-RSservice(server-side)">Exampl
 e #6: Client and Server with asynchronous JAX-RS service (server-side)</a></li><li><a shape="rect" href="#UsingOpenTracing-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example #7: Client and Server with asynchronous invocation (client-side)</a></li></ul>
+</li><li><a shape="rect" href="#UsingOpenTracing-DistributedTracingwithOpenTracingandJAX-WSsupport">Distributed Tracing with OpenTracing and JAX-WS support</a></li></ul>
+</div><h1 id="UsingOpenTracing-Overview">Overview</h1><p><a shape="rect" class="external-link" href="http://opentracing.io/" rel="nofollow">OpenTracing</a> is a vendor-neutral open standard for distributed tracing. Essentially, for Java-based projects the specification exists as a set of <a shape="rect" class="external-link" href="https://github.com/opentracing/opentracing-java" rel="nofollow">Java APIs</a> which any distributed tracing solution is welcome to implement. There are<a shape="rect" class="external-link" href="http://opentracing.io/documentation/pages/supported-tracers" rel="nofollow"> quite a few distributed tracing frameworks</a> available which are compatible with <a shape="rect" class="external-link" href="http://opentracing.io/" rel="nofollow">OpenTracing</a>, notably <a shape="rect" class="external-link" href="http://zipkin.io/" rel="nofollow">Zipkin</a> (via community contributions like <a shape="rect" class="external-link" href="https://github.com/openzipkin/brav
 e-opentracing" rel="nofollow">bridge from Brave to OpenTracing</a> ), <a shape="rect" class="external-link" href="http://lightstep.com/" rel="nofollow">Lightstep</a> and <a shape="rect" class="external-link" href="https://uber.github.io/jaeger/" rel="nofollow">Jaeger</a>. Starting from <strong>3.2.1</strong> release, Apache CXF fully supports integration (through <strong>cxf-integration-tracing-opentracing</strong> module) with any distributed tracer that provides <a shape="rect" class="external-link" href="http://opentracing.io/" rel="nofollow">OpenTracing</a>&#160;<a shape="rect" class="external-link" href="https://github.com/opentracing/opentracing-java" rel="nofollow">Java API</a> implementation.</p><p>The section <a shape="rect" href="https://cwiki.apache.org/confluence/display/CXF20DOC/Using+Apache+HTrace">dedicated to Apache HTrace </a>has pretty good introduction into distributed tracing basics however <a shape="rect" class="external-link" href="http://opentracing.io/" rel="
 nofollow">OpenTracing</a> specification abstracts a lot of things, outlining just a general APIs to denote the <strong>Span&#160;</strong>lifecycle and injection points to propagate the context across many distributed components. As such, the intrinsic details about HTTP headers f.e. becomes an integral part of the distributed tracer of your choice, out of reach for Apache CXF.</p><h1 id="UsingOpenTracing-DistributedTracinginApacheCXFusingOpenTracing">Distributed Tracing in Apache CXF using OpenTracing</h1><p><a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> is a very popular framework for building services and web APIs. No doubts, it is going to play even more important role in context of microservices architecture letting developers to quickly build and deploy individual JAX-RS/JAX-WS services. Distributed tracing is an essential technique to observe the application platform as a whole, breaking the request to individual service traces as it goes through and crosses the
  boundaries of threads, processes and machines.</p><p>The current integration of distributed tracing in <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> supports&#160;<a shape="rect" class="external-link" href="http://opentracing.io/" rel="nofollow">OpenTracing</a>&#160;<a shape="rect" class="external-link" href="https://github.com/opentracing/opentracing-java" rel="nofollow">Java API</a> <strong class="external-link">0.30.0+</strong> and provides full-fledged support of JAX-RS 2.x / JAX-WS applications. From high-level prospective, the JAX-RS integration consists of three main parts:</p><ul><li><strong>TracerContext</strong> (injectable through <strong>@Context</strong> annotation)</li><li><strong>OpenTracingProvider</strong> (server-side JAX-RS provider) and <strong>OpenTracingClientProvider</strong> (client-side JAX-RS provider)</li><li class="external-link"><strong>OpenTracingFeature</strong> (server-side JAX-RS feature) to simplify the configuration and integration<
 /li></ul><p>Similarly, from high-level perspective,&#160;JAX-WS integration includes:</p><ul><li><strong>OpenTracingStartInterceptor</strong> / <strong>OpenTracingStopInterceptor</strong> / <strong>OpenTracingFeature&#160;</strong><a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> feature (server-side JAX-WS support)</li><li><strong>OpenTracingClientStartInterceptor</strong> / <strong>OpenTracingClientStopInterceptor</strong> / <strong>OpenTracingClientFeature&#160;</strong><a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> feature (client-side JAX-WS support)</li></ul><p><a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> uses HTTP headers to hand off tracing context from the client to the service and from the service to service. Those headers are specific to distributing tracing framework you have picked and are not configurable at the moment (unless the framework itself has a way to do that).</p><p>By default, <strong>OpenTracingClientProvider</strong
 > will try to pass the currently active <strong>span</strong> through HTTP headers on each service invocation. If there is no active spans, the new span will be created and passed through HTTP headers on per-invocation basis. Essentially, for JAX-RS applications just registering <strong>OpenTracingClientProvider</strong> on the client and <strong>OpenTracingProvider</strong> on the server is enough to have tracing context to be properly passed everywhere. The only configuration part which is necessary are <strong>span reports(s)</strong> and <strong>sampler</strong>(s) which are, not surprisingly, specific to distributing tracing framework you have chosen.</p><p>It is also worth to mention the way <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> attaches the description to <strong>spans</strong>. With regards to the client integration, the description becomes a full URL being invoked prefixed by HTTP method, for example: <strong>GET </strong><a shape="rect" class="extern
 al-link" href="http://localhost:8282/books" rel="nofollow"><strong>http://localhost:8282</strong>/books</a>. On the server side integration, the description becomes a relative JAX-RS resource path prefixed by HTTP method, f.e.: <strong>GET books, POST book/123</strong></p><h1 id="UsingOpenTracing-ConfiguringClient">Configuring Client</h1><p>In this section and below, all the code snippets are going to be based on <a shape="rect" class="external-link" href="https://uber.github.io/jaeger/" rel="nofollow">Jaeger</a> distributed tracing framework (<strong>release 0.20.6+</strong>), although everything we are going to discuss is equally applicable to any other existing alternatives. Essentially, the only dependency <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> integration relies on is the <strong>Tracer</strong> instance.</p><p>There are a couple of ways the JAX-RS client could be configured, depending on the client implementation. <a shape="rect" href="http://cxf.apache.o
 rg/">Apache CXF</a> provides its own <strong>WebClient</strong> which could be configured just like that (in future versions, there would be a simpler ways to do that using client specific features):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Tracer tracer = new Configuration("web-client", 
+        new Configuration.SamplerConfiguration(ConstSampler.TYPE, 1), /* or any other Sampler */
+        new Configuration.ReporterConfiguration(new HttpSender("http://localhost:14268/api/traces")) /* or any other Sender */
+    ).getTracer();
+                
+Response response = WebClient
+    .create("http://localhost:9000/catalog", Arrays.asList(new OpenTracingClientProvider(tracer)))
+    .accept(MediaType.APPLICATION_JSON)
+    .get();</pre>
+</div></div><p>The configuration based on using the standard JAX-RS <strong>Client</strong> is very similar:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Tracer tracer = new Configuration("jaxrs-client", 
+        new Configuration.SamplerConfiguration(ConstSampler.TYPE, 1), /* or any other Sampler */
+        new Configuration.ReporterConfiguration(new HttpSender("http://localhost:14268/api/traces")) /* or any other Sender */
+    ).getTracer();
+                
+final OpenTracingClientProvider provider = new OpenTracingClientProvider(tracer);
+final Client client = ClientBuilder.newClient().register(provider);
+    
+final Response response = client
+  .target("http://localhost:9000/catalog")
+  .request()
+  .accept(MediaType.APPLICATION_JSON)
+  .get();</pre>
+</div></div><p>Alternatively, you may use <strong>GlobalTracer</strong> to pass the tracer around, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Tracer tracer = new Configuration("jaxrs-client", 
+        new Configuration.SamplerConfiguration(ConstSampler.TYPE, 1), /* or any other Sampler */
+        new Configuration.ReporterConfiguration(new HttpSender("http://localhost:14268/api/traces")) /* or any other Sender */
+    ).getTracer();
+
+// This method should only be called once during the application initialization phase.
+GlobalTracer.register(tracer);
+
+// No explicit Tracer instance is required, it will be picked off the GlobalTracer using get() method
+final OpenTracingClientProvider provider = new OpenTracingClientProvider();</pre>
+</div></div><h1 id="UsingOpenTracing-ConfiguringServer">Configuring Server</h1><p>Server configuration is a bit simpler than the client one thanks to the feature class available, <strong>OpenTracingFeature</strong>. Depending on the way the&#160;<a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> is used to configure JAX-RS services, it could be part of JAX-RS application configuration, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@ApplicationPath( "/" )
+public class CatalogApplication extends Application {
+    @Override
+    public Set&lt;Object&gt; getSingletons() {
+        final Tracer tracer = new Configuration("tracer-server", 
+                new Configuration.SamplerConfiguration(ConstSampler.TYPE, 1), /* or any other Sampler */
+                new Configuration.ReporterConfiguration(new HttpSender("http://localhost:14268/api/traces")) /* or any other Sender */
+            ).getTracer();
+
+            
+        return new HashSet&lt;&gt;(
+                Arrays.asList(
+                    new OpenTracingFeature(tracer)
+                )
+            );
+    } 
+}</pre>
+</div></div><p>Or it could be configured using <strong>JAXRSServerFactoryBean</strong> as well, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Tracer tracer = new Configuration("tracer-server", 
+        new Configuration.SamplerConfiguration(ConstSampler.TYPE, 1), /* or any other Sampler */
+        new Configuration.ReporterConfiguration(new HttpSender("http://localhost:14268/api/traces")) /* or any other Sender */
+    ).getTracer();
+
+final JAXRSServerFactoryBean factory = RuntimeDelegate.getInstance().createEndpoint(/* application instance */, JAXRSServerFactoryBean.class);
+factory.setProvider(new OpenTracingFeature(tracer));
+...
+return factory.create();</pre>
+</div></div><p>Alternatively, you may rely on <strong>GlobalTracer</strong> to pass the tracer around, so in this case the <strong>OpenTracingFeature</strong> will pick it up from there, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@ApplicationPath( "/" )
+public class CatalogApplication extends Application {
+    @Override
+    public Set&lt;Object&gt; getSingletons() {
+        return new HashSet&lt;&gt;(
+                Arrays.asList(
+                    // No explicit Tracer instance is required, it will be picked off the GlobalTracer using get() method
+                    new OpenTracingFeature()
+                )
+            );
+    } 
+}</pre>
+</div></div><p>Once the <strong>span reporter</strong> and <strong>sampler</strong> are properly configured, all generated <strong>spans</strong> are going to be collected and available for analysis and/or visualization.</p><h1 id="UsingOpenTracing-DistributedTracingInAction:UsageScenarios">Distributed Tracing In Action: Usage Scenarios</h1><p class="confluence-link">In the following subsections we are going to walk through many different scenarios to illustrate the distributed tracing in action, starting from the simplest ones and finishing with asynchronous JAX-RS services. All examples assume that configuration <strong>has been done</strong> (see please <a shape="rect" href="https://cwiki.apache.org/confluence/display/CXF20DOC/Using+OpenTracing#UsingOpenTracing-ConfiguringClient"><span class="confluence-link"><span class="confluence-link">Configuring Client</span></span></a><span class="confluence-link">&#160;</span> and<a shape="rect" href="https://cwiki.apache.org/confluence/di
 splay/CXF20DOC/Using+OpenTracing#UsingOpenTracing-configuringserver"><span class="confluence-link">&#160;</span></a><a shape="rect" href="https://cwiki.apache.org/confluence/display/CXF20DOC/Using+OpenTracing#UsingOpenTracing-ConfiguringServer"><span class="confluence-link">Configuring Server</span></a> sections above).</p><h2 id="UsingOpenTracing-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example #1: Client and Server with default distributed tracing configured</h2><p>In the first example we are going to see the effect of using default configuration on the client and on the server, with only <strong>OpenTracingClientProvider</strong>&#160; and <strong><strong>OpenTracing</strong>Provider</strong> registered. The JAX-RS resource endpoint is pretty basic stubbed method:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+@GET
+public Collection&lt;Book&gt; getBooks() {
+    return Arrays.asList(
+        new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev Hathi")
+    );
+}</pre>
+</div></div><p>The client is as simple as that:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Response response = client
+    .target("http://localhost:8282/books")
+    .request()
+    .accept(MediaType.APPLICATION_JSON)
+    .get();</pre>
+</div></div><p>The actual invocation of the request by the client (with service name <strong>tracer-client</strong>) and consequent invocation of the service on the server side (service name<strong> tracer-server</strong>) is going to generate the following sample traces (taken from <a shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui" rel="nofollow">Jaeger UI</a>):</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2012:41:7.png"></span></p><p>The same trace will be looking pretty similar using traditional <a shape="rect" class="external-link" href="https://github.com/openzipkin/zipkin/tree/master/zipkin-ui" rel="nofollow">Zipkin UI</a> frontend:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2013:18
 :20.png"></span></p><h2 id="UsingOpenTracing-Example#2:ClientandServerwithnestedtrace">Example #2: Client and Server with nested trace</h2><p>In this example server-side implementation of the JAX-RS service is going to call an external system (simulated as a simple delay of 500ms) within its own span. The client-side code stays unchanged.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+@GET
+public Collection&lt;Book&gt; getBooks(@Context final TracerContext tracer) throws Exception {
+    try(final ActiveSpan scope = tracer.startSpan("Calling External System")) {
+        // Simulating a delay of 500ms required to call external system
+        Thread.sleep(500);
+            
+        return Arrays.asList(
+            new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev Hathi")
+        );
+    }
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with service name <strong><span class="label label-default service-filter-label service-tag-filtered"><strong>tracer</strong>-client</span></strong>) and consequent invocation of the service on the server side (service name<strong><span class="label label-default service-filter-label"><strong> tracer-</strong>server</span></strong><span class="label label-default service-filter-label">)</span> is going to generate the following sample traces (taken from <a shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui" rel="nofollow">Jaeger UI</a>):</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:9:7.png"></span></p><p>The same trace will be looking pretty similar using traditional <a shape="rect" class="external-link" href="https://github.com/openzipkin/zipkin/tree/mast
 er/zipkin-ui" rel="nofollow">Zipkin UI</a> frontend:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:10:40.png"></span></p><h2 id="UsingOpenTracing-Example#3:ClientandServertracewithtimeline">Example #3: Client and Server trace with timeline</h2><p>In this example server-side implementation of the JAX-RS service is going to add timeline to the active span. The client-side code stays unchanged.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+@GET
+public Collection&lt;Book&gt; getBooks(@Context final TracerContext tracer) throws Exception {
+    tracer.timeline("Preparing Books");
+    // Simulating some work using a delay of 100ms
+    Thread.sleep(100);
+         
+    return Arrays.asList(
+        new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev Hathi")
+    );
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with service name <strong><span class="label label-default service-filter-label service-tag-filtered">tracer-client</span></strong>) and consequent invocation of the service on the server side (service name<strong> <span class="label label-default service-filter-label">traceser-server</span></strong>) is going to generate the following sample traces (taken from <a shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui" rel="nofollow">Jaeger UI</a>):</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="400" src="using-opentracing.data/image2017-9-10%2014:26:23.png"></span></p><p>&#160;</p><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Please
  notice that timelines are treated as<strong> logs events</strong> in <a shape="rect" class="external-link" href="https://uber.github.io/jaeger/" rel="nofollow">Jaeger</a>.</p></div></div><p>The same trace will be looking pretty similar using traditional <a shape="rect" class="external-link" href="https://github.com/openzipkin/zipkin/tree/master/zipkin-ui" rel="nofollow">Zipkin UI</a> frontend:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:19:1.png"></span></p><h2 id="UsingOpenTracing-Example#4:ClientandServerwithbinaryannotations(key/value)">Example #4: Client and Server with binary annotations (key/value)</h2><p>In this example server-side implementation of the JAX-RS service is going to add key/value annotations to the active span. The client-side code stays unchanged.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeC
 ontent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+@GET
+public Collection&lt;Book&gt; getBooks(@Context final TracerContext tracer) throws Exception {
+    final Collection&lt;Book&gt; books = Arrays.asList(
+        new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev Hathi")
+    );
+         
+    tracer.annotate("# of books", Integer.toString(books.size()));
+    return books;
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with service name <strong><span class="label label-default service-filter-label service-tag-filtered"><strong><span class="label label-default service-filter-label service-tag-filtered"><strong>tracer</strong></span></strong>-client</span></strong>) and consequent invocation of the service on the server side (service name<strong> tracer-<span class="label label-default service-filter-label">server</span></strong>) is going to generate the following sample server trace properties (taken from <a shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui" rel="nofollow">Jaeger UI</a>):</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="400" src="using-opentracing.data/image2017-9-10%2014:40:20.png"></span></p><p>The same trace will be looking pretty similar using traditional <a shape="rect" class="external-link" href="https:
 //github.com/openzipkin/zipkin/tree/master/zipkin-ui" rel="nofollow">Zipkin UI</a> frontend:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:46:4.png"></span></p><h2 id="UsingOpenTracing-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example #5: Client and Server with parallel trace (involving thread pools)</h2><p>In this example server-side implementation of the JAX-RS service is going to offload some work into thread pool and then return the response to the client, simulating parallel execution. The client-side code stays unchanged.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+@GET
+public Collection&lt;Book&gt; getBooks(@Context final TracerContext tracer) throws Exception {
+    final Future&lt;Book&gt; book1 = executor.submit(
+        tracer.wrap("Getting Book 1", new Traceable&lt;Book&gt;() {
+            public Book call(final TracerContext context) throws Exception {
+                // Simulating a delay of 100ms required to call external system
+                Thread.sleep(100);
+                     
+                return new Book("Apache CXF Web Service Development", 
+                    "Naveen Balani, Rajeev Hathi");
+            }
+        })
+    );
+         
+    final Future&lt;Book&gt; book2 = executor.submit(
+        tracer.wrap("Getting Book 2", new Traceable&lt;Book&gt;() {
+            public Book call(final TracerContext context) throws Exception {
+                // Simulating a delay of 100ms required to call external system
+                Thread.sleep(200);
+                     
+                return new Book("Developing Web Services with Apache CXF and Axis2", 
+                    "Kent Ka Iok Tong");
+            }
+        })
+    );
+        
+    return Arrays.asList(book1.get(), book2.get());
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with service name <strong>tracer-<span class="label label-default service-filter-label service-tag-filtered">client</span></strong>) and consequent invocation of the service on the server side (process name<strong> tracer-<span class="label label-default service-filter-label">server</span></strong>) is going to generate the following sample traces (taken from <a shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui" rel="nofollow">Jaeger UI</a>):</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:49:4.png"></span></p><p>The same trace will be looking pretty similar using traditional <a shape="rect" class="external-link" href="https://github.com/openzipkin/zipkin/tree/master/zipkin-ui" rel="nofollow">Zipkin UI</a> frontend:</p><p><span class="confluence-embedded-fil
 e-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:50:2.png"></span></p><h2 id="UsingOpenTracing-Example#6:ClientandServerwithasynchronousJAX-RSservice(server-side)">Example #6: Client and Server with asynchronous JAX-RS service (server-side)</h2><p>In this example server-side implementation of the JAX-RS service is going to be executed asynchronously. It poses a challenge from the tracing prospective as request and response are processed in different threads (in general). At the moment, <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> does not support the transparent tracing spans management (except for default use case) but provides the simple ways to do that (by letting to transfer spans from thread to thread). The client-side code stays unchanged.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+@GET
+public void getBooks(@Suspended final AsyncResponse response, @Context final TracerContext tracer) throws Exception {
+    tracer.continueSpan(new Traceable&lt;Future&lt;Void&gt;&gt;() {
+        public Future&lt;Void&gt; call(final TracerContext context) throws Exception {
+            return executor.submit(
+                tracer.wrap("Getting Book", new Traceable&lt;Void&gt;() {
+                    public Void call(final TracerContext context) throws Exception {
+                        // Simulating a processing delay of 50ms
+                        Thread.sleep(50);
+                             
+                        response.resume(
+                            Arrays.asList(
+                                new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev Hathi")
+                            )
+                        );
+                             
+                        return null;
+                    }
+                })
+            );
+        }
+    });
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with service name <strong>tracer-<span class="label label-default service-filter-label service-tag-filtered">client</span></strong>) and consequent invocation of the service on the server side (service name<strong> tracer-<span class="label label-default service-filter-label">server</span></strong>) is going to generate the following sample traces (taken from <a shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui" rel="nofollow">Jaeger UI</a>):</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:54:2.png"></span></p><p>The same trace will be looking pretty similar using traditional <a shape="rect" class="external-link" href="https://github.com/openzipkin/zipkin/tree/master/zipkin-ui" rel="nofollow">Zipkin UI</a> frontend:</p><p><span class="confluence-embedded-fil
 e-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:55:0.png"></span></p><h2 id="UsingOpenTracing-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example #7: Client and Server with asynchronous invocation (client-side)</h2><p>In this example server-side implementation of the JAX-RS service is going to be the default one:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+@GET
+public Collection&lt;Book&gt; getBooks() {
+    return Arrays.asList(
+        new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev Hathi")
+    );
+}</pre>
+</div></div><p>While the JAX-RS client&#160;implementation is going to perform the asynchronous invocation:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Future&lt;Response&gt; future = client
+    .target("http://localhost:8282/books")
+    .request()
+    .accept(MediaType.APPLICATION_JSON)
+    .async()
+    .get();</pre>
+</div></div><p>In this respect, there is no difference from the caller prospective however a bit more work is going under the hood to transfer the active tracing span from JAX-RS client request filter to client response filter as in general those are executed in different threads (similarly to server-side asynchronous JAX-RS resource invocation). The actual invocation of the request by the client (with service name <strong>tracer-<span class="label label-default service-filter-label service-tag-filtered">client</span></strong>) and consequent invocation of the service on the server side (service name<strong> tracer-<span class="label label-default service-filter-label">server</span></strong>) is going to generate the following sample traces (taken from <a shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui" rel="nofollow">Jaeger UI</a>):</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" 
 height="250" src="using-opentracing.data/image2017-9-10%2015:0:49.png"></span></p><p>The same trace will be looking pretty similar using traditional <a shape="rect" class="external-link" href="https://github.com/openzipkin/zipkin/tree/master/zipkin-ui" rel="nofollow">Zipkin UI</a> frontend:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-opentracing.data/image2017-9-10%2014:58:53.png"></span></p><h1 id="UsingOpenTracing-DistributedTracingwithOpenTracingandJAX-WSsupport">Distributed Tracing with OpenTracing and JAX-WS support</h1><p>Distributed tracing in the <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> is build primarily around JAX-RS 2.x implementation. However, JAX-WS is also supported but it requires to write some boiler-plate code and use&#160;<a shape="rect" class="external-link" href="http://opentracing.io/" rel="nofollow">OpenTracing</a>&#160;<a shape="rect" cla
 ss="external-link" href="https://github.com/opentracing/opentracing-java" rel="nofollow">Java API</a>  directly (the JAX-WS integration is going to be enhanced in the future). Essentially, from the server-side prospective the in/out interceptors, <strong>OpenTracingStartInterceptor</strong> and <strong><strong>OpenTracing</strong>StopInterceptor </strong>respectively, should be configured as part of interceptor chains, either manually or using <strong><strong>OpenTracing</strong>Feature</strong>. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Tracer tracer = new Configuration("tracer", 
+        new Configuration.SamplerConfiguration(ConstSampler.TYPE, 1), /* or any other Sampler */
+        new Configuration.ReporterConfiguration(new HttpSender("http://localhost:14268/api/traces")) /* or any other Sender */
+    ).getTracer();
+
+final JaxWsServerFactoryBean sf = new JaxWsServerFactoryBean();
+...
+sf.getFeatures().add(new OpenTracingFeature(trace));
+...
+sf.create();</pre>
+</div></div><p>Similarly to the server-side, client-side needs own set of out/in interceptors, <strong><strong>OpenTracing</strong>ClientStartInterceptor</strong> and <strong><strong>OpenTracing</strong>ClientStopInterceptor</strong> (or <strong><strong>OpenTracing</strong>ClientFeature</strong>). Please notice the difference from server-side:&#160; <strong><strong>OpenTracing</strong>ClientStartInterceptor</strong> becomes out-interceptor while <strong><strong>OpenTracing</strong>ClientStopInterceptor</strong> becomes in-interceptor. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">final Tracer tracer = new Configuration("tracer", 
+        new Configuration.SamplerConfiguration(ConstSampler.TYPE, 1), /* or any other Sampler */
+        new Configuration.ReporterConfiguration(new HttpSender("http://localhost:14268/api/traces")) /* or any other Sender */
+    ).getTracer();
+              
+final JaxWsProxyFactoryBean sf = new JaxWsProxyFactoryBean();
+...
+sf.getFeatures().add(new OpenTracingClientFeature(tracer));
+...
+sf.create();
+
+</pre>
+</div></div><p>As it was mentioned before, you may use <strong>GlobalTracer</strong> utility class to pass the tracer around so, for example, any JAX-WS service will be able to retrieve the current tracer by invoking <strong>GlobalTracer.get()</strong> method.</p></div>
+           </div>
+           <!-- Content -->
+         </td>
+        </tr>
+      </table>
+   </td>
+   <td id="cell-2-2" colspan="2">&nbsp;</td>
+  </tr>
+  <tr>
+   <td id="cell-3-0">&nbsp;</td>
+   <td id="cell-3-1">&nbsp;</td>
+   <td id="cell-3-2">
+     <div id="footer">
+       <!-- Footer -->
+       <div id="site-footer">
+         <a href="http://cxf.apache.org/privacy-policy.html">Privacy Policy</a> - 
+         (<a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=73637478">edit page</a>) 
+	 (<a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=73637478&amp;showComments=true&amp;showCommentArea=true#addcomment">add comment</a>)<br>
+	Apache CXF, CXF, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.<br>
+        All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+       </div>
+       <!-- Footer -->
+     </div>
+   </td>
+   <td id="cell-3-3">&nbsp;</td>
+   <td id="cell-3-4">&nbsp;</td>
+  </tr>
+  <tr>
+    <td id="cell-4-0" colspan="2">&nbsp;</td>
+    <td id="cell-4-1">&nbsp;</td>
+    <td id="cell-4-2" colspan="2">&nbsp;</td>
+  </tr>
+</table>
+
+<script type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+try {
+var pageTracker = _gat._getTracker("UA-4458903-1");
+pageTracker._trackPageview();
+} catch(err) {}</script>
+
+</body>
+</html>
+



Mime
View raw message