You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by dk...@apache.org on 2017/09/13 15:05:57 UTC
svn commit: r1018111 [26/33] - in /websites/production/cxf/content: ./
cache/ docs/
Modified: websites/production/cxf/content/docs/tls-configuration.html
==============================================================================
--- websites/production/cxf/content/docs/tls-configuration.html (original)
+++ websites/production/cxf/content/docs/tls-configuration.html Wed Sep 13 15:05:52 2017
@@ -117,11 +117,11 @@ Apache CXF -- TLS Configuration
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311218394 {padding: 0px;}
-div.rbtoc1505311218394 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311218394 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314919643 {padding: 0px;}
+div.rbtoc1505314919643 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314919643 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311218394">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314919643">
<ul class="toc-indentation"><li><a shape="rect" href="#TLSConfiguration-TLSParameterscommontobothClientsandServers">TLS Parameters common to both Clients and Servers</a>
<ul class="toc-indentation"><li><a shape="rect" href="#TLSConfiguration-KeyManagers">Key Managers</a></li><li><a shape="rect" href="#TLSConfiguration-TrustManagers">Trust Managers</a></li><li><a shape="rect" href="#TLSConfiguration-CipherSuitesFilter">CipherSuites Filter</a></li><li><a shape="rect" href="#TLSConfiguration-CertConstraints">Cert Constraints</a></li></ul>
</li><li><a shape="rect" href="#TLSConfiguration-ClientTLSParameters">Client TLS Parameters</a>
@@ -130,7 +130,7 @@ div.rbtoc1505311218394 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect" href="#TLSConfiguration-ClientAuthentication">Client Authentication</a></li></ul>
</li></ul>
</div><h1 id="TLSConfiguration-TLSParameterscommontobothClientsandServers">TLS Parameters common to both Clients and Servers</h1><p>The TLS Parameters common to both Clients and Servers are given <a shape="rect" class="external-link" href="https://svn.apache.org/repos/asf/cxf/trunk/core/src/main/java/org/apache/cxf/configuration/jsse/TLSParameterBase.java">here</a>:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Attribute</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>keyManagers</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JVM default Key Managers</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Key Managers to hold X509 certificates.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>tru
stManagers</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JVM default Trust Managers</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>TrustManagers to validate peer X509 certificates.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>jsseProvider</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JVM default provider associated with protocol</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JSSE provider name.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>cipherSuites</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JVM default cipher suites</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>CipherSuites that will be supported.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>cipherSuitesFilter</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd
"><p>filters of the supported CipherSuites that will be supported and used if available.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>certConstraints</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Certificate Constraints specification.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>secureRandomParameters</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JVM default Secure Random</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>SecureRandom specification.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>secureSocketProtocol</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>"TLS"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Protocol Name. Most common example are "SSL", "TLS" or "TLSv1".</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><co
de>certAlias</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Cert alias to use. Useful when keystore has multiple certs.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>enableRevocation</code> <strong>CXF 3.1.11</strong></td><td colspan="1" rowspan="1" class="confluenceTd">"false"</td><td colspan="1" rowspan="1" class="confluenceTd"><p>This attribute specifies whether to enable revocation when checking the client/server certificate.</p><p>To enable "ocsp" this should be set to "true" (along with the Java Security property "ocsp.enable").</p></td></tr></tbody></table></div><p> </p><p>Note that from CXF 3.0.3 and 2.7.14, the SSLv3 protocol is disabled on the client side, and on the service side (if Jetty is used), unless "SSLv3" is explicitly specified for the "secureSocketProtocol" parameter.</p><h2 id="TLSConfiguration-KeyManagers">Key Managers</h2><p>The Key Managers c
onfiguration item is used to retrieve key information. It is required for a Server, but is only required for a Client when the Server requires Client Authentication.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Key Manager sample</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;"> <httpj:tlsServerParameters>
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> <httpj:tlsServerParameters>
...
<sec:keyManagers keyPassword="stskpass">
<sec:keyStore type="jks" password="stsspass" resource="stsstore.jks" />
@@ -139,7 +139,7 @@ div.rbtoc1505311218394 li {margin-left:
</httpj:tlsServerParameters>
</pre>
</div></div><h2 id="TLSConfiguration-TrustManagers">Trust Managers</h2><p>The Trust Managers configuration item is used to validate trust in peer X.509 certificates. It is required for both Servers and Clients.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Trust Manager sample</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;"> <httpj:tlsServerParameters>
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> <httpj:tlsServerParameters>
...
<sec:trustManagers>
<sec:keyStore type="jks" password="stsspass" resource="stsstore.jks" />
@@ -148,7 +148,7 @@ div.rbtoc1505311218394 li {margin-left:
</httpj:tlsServerParameters>
</pre>
</div></div><h2 id="TLSConfiguration-CipherSuitesFilter">CipherSuites Filter</h2><p>The CipherSuites Filter is used to either include or exclude particular CipherSuites. If no exclusion filter is specified, the default is to exclude all "NULL" and "anon" filters. CXF 3.0.3 onwards excludes all "DES" filters as well, and 3.0.4 onwards additionally excludes all "EXPORT" filters.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>CipherSuites Filter sample</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;"> <httpj:tlsServerParameters>
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> <httpj:tlsServerParameters>
...
<sec:cipherSuitesFilter>
<sec:include>.*_EXPORT_.*</sec:include>
@@ -161,7 +161,7 @@ div.rbtoc1505311218394 li {margin-left:
</httpj:tlsServerParameters>
</pre>
</div></div><h2 id="TLSConfiguration-CertConstraints">Cert Constraints</h2><p>Cert constraints can be used by either the client or server to impose constraints on the peer certificates. This can be done by specifying a set of regular expressions on either the Subject DN (Distinguished Name) or the Issuer DN (or both) of the certificate. A "combinator" attribute can also be specified for either the SubjectDNConstraints or IssuerDNConstraints Elements. This attribute can be either "ANY" or "ALL", and refers to whether any or all of the defined regular expressions should apply. The default value is "ALL".</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>CipherSuites Filter sample</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;"> <httpj:tlsServerParameters>
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> <httpj:tlsServerParameters>
...
<sec:certConstraints>
<sec:SubjectDNConstraints>
@@ -176,13 +176,13 @@ div.rbtoc1505311218394 li {margin-left:
</httpj:tlsServerParameters>
</pre>
</div></div><h1 id="TLSConfiguration-ClientTLSParameters">Client TLS Parameters</h1><p>In addition to the TLS Parameters common to both Clients and Servers, there are some parameters that are <a shape="rect" class="external-link" href="https://svn.apache.org/repos/asf/cxf/trunk/core/src/main/java/org/apache/cxf/configuration/jsse/TLSClientParameters.java">specific</a> to Clients:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Attribute</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>disableCNCheck</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Indicates whether that the hostname given in the HTTPS URL will be checked against the service's Common Nam
e (CN) given in its certificate during requests, and failing if there is a mismatch. If set to <code>true</code> (<strong>not recommended for production use</strong>), such checks will be bypassed. That will allow you, for example, to use a URL such as <code>localhost</code> during development.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>sslSocketFactory</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>A SSLSocketFactory to use. All other bean properties are ignored if this is set.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>sslCacheTimeout</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>86400 seconds (24 hours)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>SSL Cache Timeout in seconds.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>useHttpsURLConnectionDefaultSslSocketFactory</
code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>This attribute specifies if <a shape="rect" class="external-link" href="http://java.sun.com/javase/6/docs/api/javax/net/ssl/HttpsURLConnection.html#getDefaultSSLSocketFactory()" rel="nofollow">HttpsURLConnection.getDefaultSSLSocketFactory()</a> should be used to create https connections. If '<code>true</code>', '<code>jsseProvider</code>', '<code>secureSocketProtocol</code>', '<code>trustManagers</code>', '<code>keyManagers</code>', '<code>secureRandom</code>', '<code>cipherSuites</code>' and '<code>cipherSuitesFilter</code>' configuration parameters are ignored.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>useHttpsURLConnectionDefaultHostnameVerifier</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>This attribute s
pecifies if <a shape="rect" class="external-link" href="http://java.sun.com/javase/6/docs/api/javax/net/ssl/HttpsURLConnection.html#getDefaultHostnameVerifier()" rel="nofollow">HttpsURLConnection.getDefaultHostnameVerifier()</a> should be used to create https connections. If '<code>true</code>', '<code>disableCNCheck</code>' configuration parameter is ignored.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">hostnameVerifier</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">A custom HostnameVerifier instance to use</td></tr></tbody></table></div><h2 id="TLSConfiguration-DisableCNCheck">Disable CN Check</h2><p><code>disableCNCheck</code> is a parameterized boolean, you can use a fixed variable <code>true</code>|<code>false</code> as well as a <a shape="rect" class="external-link" href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-placeholderconf
igurer" rel="nofollow">Spring externalized property</a> variable (e.g. <code>${disable-https-hostname-verification</code>}) or a <a shape="rect" class="external-link" href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#expressions-beandef" rel="nofollow">Spring expression</a> (e.g. <code>#{systemProperties['dev-mode']</code>}).</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>HTTP conduit configuration disabling HTTP URL hostname verification (usage of localhost, etc)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;"> <!-- deactivate HTTPS url hostname verification (localhost, etc) -->
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> <!-- deactivate HTTPS url hostname verification (localhost, etc) -->
<!-- WARNING ! disableCNcheck=true should NOT be used in production -->
<http-conf:tlsClientParameters disableCNCheck="true" />
...
</pre>
</div></div><h1 id="TLSConfiguration-ServerTLSParameters">Server TLS Parameters</h1><p>In addition to the TLS Parameters common to both Clients and Servers, there are some parameters that are <a shape="rect" class="external-link" href="https://svn.apache.org/repos/asf/cxf/trunk/core/src/main/java/org/apache/cxf/configuration/jsse/TLSServerParameters.java">specific</a> to Servers:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Attribute</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>clientAuthentication</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Not "wanted" or "required"</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Allows you to configure whether client authentication is "wanted" and/or "required.</p></td><
/tr><tr><td colspan="1" rowspan="1" class="confluenceTd">excludeProtocols</td><td colspan="1" rowspan="1" class="confluenceTd">SSLv3 is disabled by default for Jetty from CXF 3.0.3 + 2.7.14</td><td colspan="1" rowspan="1" class="confluenceTd">The TLS protocols to exclude.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">includeProtocols <strong>CXF 3.1.1/3.0.6</strong></td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Allows you to add more protocols. For example, if you have a TLS protocol you could add support for "SSLv2Hello" here, for older clients.</td></tr></tbody></table></div><h2 id="TLSConfiguration-ClientAuthentication">Client Authentication</h2><p>This allows you to define whether client authentication is wanted and/or required.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Client Authentication sample</b></di
v><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;"> <httpj:tlsServerParameters>
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> <httpj:tlsServerParameters>
...
<sec:clientAuthentication want="true" required="true" />
...
Modified: websites/production/cxf/content/docs/transformationfeature.html
==============================================================================
--- websites/production/cxf/content/docs/transformationfeature.html (original)
+++ websites/production/cxf/content/docs/transformationfeature.html Wed Sep 13 15:05:52 2017
@@ -32,8 +32,8 @@
<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 src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -118,11 +118,11 @@ Apache CXF -- TransformationFeature
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1 id="TransformationFeature-TransformationFeature">Transformation Feature</h1><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311196623 {padding: 0px;}
-div.rbtoc1505311196623 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311196623 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314878700 {padding: 0px;}
+div.rbtoc1505314878700 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314878700 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311196623">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314878700">
<ul class="toc-indentation"><li><a shape="rect" href="#TransformationFeature-TransformationFeature">Transformation Feature</a></li><li><a shape="rect" href="#TransformationFeature-Springconfiguration">Spring configuration</a>
<ul class="toc-indentation"><li><a shape="rect" href="#TransformationFeature-Changinginputandoutputelementnamesandnamespaces">Changing input and output element names and namespaces</a></li><li><a shape="rect" href="#TransformationFeature-Appendingnewinputandoutputelements">Appending new input and output elements</a>
<ul class="toc-indentation"><li><a shape="rect" href="#TransformationFeature-Append-Pre-Wrap">Append-Pre-Wrap</a></li><li><a shape="rect" href="#TransformationFeature-Append-Post-Wrap">Append-Post-Wrap</a></li><li><a shape="rect" href="#TransformationFeature-Append-Pre-Include">Append-Pre-Include</a></li><li><a shape="rect" href="#TransformationFeature-Append-Post-Include">Append-Post-Include</a></li><li><a shape="rect" href="#TransformationFeature-Comparingfourappendmodes">Comparing four append modes</a></li></ul>
@@ -131,7 +131,7 @@ div.rbtoc1505311196623 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect" href="#TransformationFeature-JAX-WS">JAX-WS</a></li><li><a shape="rect" href="#TransformationFeature-JAX-RS">JAX-RS</a></li></ul>
</li><li><a shape="rect" href="#TransformationFeature-Transforminterceptorsandphases">Transform interceptors and phases</a></li><li><a shape="rect" href="#TransformationFeature-Defaultnamespaceontheoutput">Default namespace on the output</a></li></ul>
</div><p>The CXF Transformation feature provides for a flexible and fast way to do dynamic transformation of inbound and/or outbound XML messages.</p><p>This feature can be used in a number of cases: dropping the namespace of the outbound messages, qualifying the incoming message, changing namespaces, appending or dropping elements and converting attributes to elements.</p><p>The "outTransformElements", "inTransformElements", "outDropElements", "inDropElements", "outAppendElements", "inAppendElements" and "attributesAsElements" properties can be used.</p><h1 id="TransformationFeature-Springconfiguration">Spring configuration</h1><h2 id="TransformationFeature-Changinginputandoutputelementnamesandnamespaces">Changing input and output element names and namespaces</h2><p>"outTransformElements" map property can be used to change the output element names and change or drop namespaces. Keys are the elements to be changed, values are the new element names. 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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="outTransformElements">
<map>
<!-- change "book" to "thebook" -->
@@ -150,7 +150,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><p>"inTransformElements" map property can be used to change the input element names and change or drop namespaces. See the "outTransfromElements" property description for an example.</p><h2 id="TransformationFeature-Appendingnewinputandoutputelements">Appending new input and output elements</h2><p>"outAppendElements" and "inAppendElements" map properties can be used to append new simple or qualified elements to the output/input in a number of ways. Keys are the elements the new elements will be appended before, values are the new elements. Examples:</p><h3 id="TransformationFeature-Append-Pre-Wrap">Append-Pre-Wrap</h3><p>Using inAppendsElements:</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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="inAppendElements">
<map>
<!-- get "book" wrapped with the new "thebook" element-->
@@ -160,7 +160,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><p>Using outAppendsElements:</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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="outAppendElements">
<map>
<!-- get "book" wrapped with the new "thebook" element-->
@@ -170,7 +170,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><h3 id="TransformationFeature-Append-Post-Wrap">Append-Post-Wrap</h3><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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="inAppendElements">
<map>
<!--
@@ -183,7 +183,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><h3 id="TransformationFeature-Append-Pre-Include">Append-Pre-Include</h3><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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="inAppendElements">
<map>
<!-- append new simple "thebook" element with a text value '2' before the "book" element -->
@@ -193,7 +193,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><h3 id="TransformationFeature-Append-Post-Include">Append-Post-Include</h3><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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="inAppendElements">
<map>
<!-- append new simple "thebook" element with a text value '2' using the "/" convention as the last child element within the "book" element -->
@@ -202,7 +202,7 @@ div.rbtoc1505311196623 li {margin-left:
</property>
</bean> </pre>
</div></div><h3 id="TransformationFeature-Comparingfourappendmodes">Comparing four append modes</h3><pre> </pre><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">input</th><th colspan="1" rowspan="1" class="confluenceTh"><p>append-pre-wrap</p><p> </p></th><th colspan="1" rowspan="1" class="confluenceTh">append-post-wrap</th><th colspan="1" rowspan="1" class="confluenceTh">append-pre-include</th><th colspan="1" rowspan="1" class="confluenceTh">append-post-include</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">key="book" value="thebook"</td><td colspan="1" rowspan="1" class="confluenceTd">key="book/" value="thebook"</td><td colspan="1" rowspan="1" class="confluenceTd">key="book" value="thebook=2"</td><td colspan="1" rowspan="1" class="confluenceTd">key="book/" value="thebook=2"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd
"><pre><sales><br clear="none"> <book><br clear="none"> <title>CXF ...</title><br clear="none"> <price>38.68</price><br clear="none"> </book><br clear="none"></sales></pre></td><td colspan="1" rowspan="1" class="confluenceTd"><pre><sales><br clear="none"> <thebook><br clear="none"> <book><br clear="none"> <title>CXF ...</title><br clear="none"> <price>38.68</price><br clear="none"> </book><br clear="none"> </thebook><br clear="none"></sales></pre></td><td colspan="1" rowspan="1" class="confluenceTd"><pre><sales><br clear="none"> <book><br clear="none"> <thebook><br clear="none"> <title>CXF ...</title><br clear="none"> <price>38.68</price><br clear="none"> </thebook><br clear="none"> </book><br clear="none"></sales></pre></td><td colspan="1" rowspan="1" class="confluenceTd"><pre><sales><br clear="no
ne"> <thebook>2</thebook><br clear="none"> <book><br clear="none"> <title>CXF ...</title><br clear="none"> <price>38.68</price><br clear="none"> </book><br clear="none"></sales></pre></td><td colspan="1" rowspan="1" class="confluenceTd"><pre><sales><br clear="none"> <book><br clear="none"> <title>CXF ...</title><br clear="none"> <price>38.68</price><br clear="none"> <thebook>2</thebook><br clear="none"> </book><br clear="none"></sales></pre></td></tr></tbody></table></div><h2 id="TransformationFeature-Replacingtextcontent">Replacing text content</h2><p>It's possible to replace the text content of a given simple element only on the input and output, 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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="inAppendElements">
<map>
<!-- replace the text content of {ns}a element with the 'new Text' value -->
@@ -212,7 +212,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><h2 id="TransformationFeature-Droppingoutputandinputelements">Dropping output and input elements</h2><p>"outDropElements" and "inDropElements" list properties can be used to drop output and input elements. Note that children elements if any of a given dropped element are not affected. Please see the "outDropElements" property description for an example. It's a so-called "shallow" drop.</p><p>Additionally, outTransformElements and inTransformElements property can be used to deep-drop an element and all of its children if any, 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;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeature" class="org.apache.cxf.feature.StaxTransformFeature">
<property name="outTransformElements">
<map>
<!-- drop "book" and all of its children, using an empty value convention -->
@@ -223,7 +223,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><h2 id="TransformationFeature-Convertingattributestoelements">Converting attributes to elements</h2><p>"attributesAsElements" boolean property can be used to have attributes serialized as elements on the output only.</p><p>The combination of "attributesAsElements" and "outDropElements" properties can be used to have certain attributes ignored in the output by turning them into elements and then blocking them.</p><h1 id="TransformationFeature-InputTransformationandRedirection">Input Transformation and Redirection</h1><p>Consider the case where a new endpoint has been introduced but some of the existing clients have not been updated yet to work with the new endpoint, they are still unaware of it.</p><p>In this case you may want to keep the CXFServlet serving the old clients but make it redirect them to a new CXFServlet serving a new endpoint only.<br clear="none"> Now, in order to serve the old clients one needs to apply a transform feature, however the new clients should
not be affected. Thus the feature can be configured such that it's only triggered if a certain contextual property has been set on a current Message. In this case the feature should only apply to the old redirected clients:</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;"><bean id="transformFeatureRest" class="org.apache.cxf.feature.StaxTransformFeature">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="transformFeatureRest" class="org.apache.cxf.feature.StaxTransformFeature">
<!--
apply the transformation only if the boolean property with the given name
is set to true on the message
@@ -233,7 +233,7 @@ div.rbtoc1505311196623 li {margin-left:
</bean>
</pre>
</div></div><h1 id="TransformationFeature-Configuringthefeaturefromthecode">Configuring the feature from the code</h1><p>The feature can be configured from the code for JAX-WS or JAX-RS clients and endpoints.</p><h2 id="TransformationFeature-JAX-WS">JAX-WS</h2><p>Here is how a JAX-WS client can be configured:</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;">CustomerServiceService service = new CustomerServiceService();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">CustomerServiceService service = new CustomerServiceService();
CustomerService customerService = service.getCustomerServicePort();
Client client = ClientProxy.getClient(customerService);
@@ -253,7 +253,7 @@ client.getInInterceptors().add(transform
</pre>
</div></div><h2 id="TransformationFeature-JAX-RS">JAX-RS</h2><p>Here is how a JAX-RS client can be configured:</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;">CustomerService customerServiceProxy = JAXRSClientFactory.create(endpointAddress, CustomerService.class);
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">CustomerService customerServiceProxy = JAXRSClientFactory.create(endpointAddress, CustomerService.class);
ClientConfiguration config = WebClient.getConfig(customerServiceProxy);
Modified: websites/production/cxf/content/docs/udp-transport.html
==============================================================================
--- websites/production/cxf/content/docs/udp-transport.html (original)
+++ websites/production/cxf/content/docs/udp-transport.html Wed Sep 13 15:05:52 2017
@@ -126,7 +126,7 @@ Apache CXF -- UDP Transport
<p>To use the UDP transport, you just need to include the cxf-rt-transports-udp module on the classpath and use a "udp://host:port" style URL for the address.</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;">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
JaxWsServerFactoryBean factory = new JaxWsServerFactoryBean();
factory.setBus(getStaticBus());
factory.setAddress("udp://localhost:8888");
@@ -147,7 +147,7 @@ Apache CXF -- UDP Transport
<p>UDP is different than the other CXF transports in that it allows multiple responses to be received for a single request. For example, if you send out a request via a multicast or broadcast, several servers could respond to that request. The basic JAX-WS generated interfaces only allow a single response to be returned to the application. However, if you use the JAX-WS Asynchronous methods, you can have CXF call the AsyncHandler for each response. To enable this, set the request property "udp.multi.response.timeout" to a timeout value greater than 0. CXF will wait that long for responses to come in before returning back to the application.</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;">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
//wait 3 seconds for responses
((BindingProvider)proxy).getRequestContext().put("udp.multi.response.timeout", 3000);
proxy.greetMeAsync("World", new AsyncHandler<String>() {
Modified: websites/production/cxf/content/docs/using-apache-htrace.html
==============================================================================
--- websites/production/cxf/content/docs/using-apache-htrace.html (original)
+++ websites/production/cxf/content/docs/using-apache-htrace.html Wed Sep 13 15:05:52 2017
@@ -32,9 +32,9 @@
<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 src='/resources/highlighter/scripts/shBrushXml.js'></script>
<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
+<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -119,11 +119,11 @@ Apache CXF -- Using Apache HTrace
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311204039 {padding: 0px;}
-div.rbtoc1505311204039 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311204039 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314857393 {padding: 0px;}
+div.rbtoc1505314857393 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314857393 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311204039">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314857393">
<ul class="toc-indentation"><li><a shape="rect" href="#UsingApacheHTrace-Overview">Overview</a></li><li><a shape="rect" href="#UsingApacheHTrace-DistributedTracinginNutshell">Distributed Tracing in Nutshell</a></li><li><a shape="rect" href="#UsingApacheHTrace-DistributedTracinginApacheCXFusingApacheHTrace">Distributed Tracing in Apache CXF using Apache HTrace</a></li><li><a shape="rect" href="#UsingApacheHTrace-ConfiguringClientconfigure.client">Configuring Client</a>
<ul class="toc-indentation"><li><a shape="rect" href="#UsingApacheHTrace-Configuringtracingheadernames">Configuring tracing header names</a></li></ul>
</li><li><a shape="rect" href="#UsingApacheHTrace-ConfiguringServerconfigure.server">Configuring Server</a>
@@ -132,7 +132,7 @@ div.rbtoc1505311204039 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect" href="#UsingApacheHTrace-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example #1: Client and Server with default distributed tracing configured</a></li><li><a shape="rect" href="#UsingApacheHTrace-Example#2:ClientandServerwithnestedtrace">Example #2: Client and Server with nested trace</a></li><li><a shape="rect" href="#UsingApacheHTrace-Example#3:ClientandServertracewithtimeline">Example #3: Client and Server trace with timeline</a></li><li><a shape="rect" href="#UsingApacheHTrace-Example#4:ClientandServerwithannotatedtrace(key/value)">Example #4: Client and Server with annotated trace (key/value)</a></li><li><a shape="rect" href="#UsingApacheHTrace-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example #5: Client and Server with parallel trace (involving thread pools)</a></li><li><a shape="rect" href="#UsingApacheHTrace-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="#UsingApacheHTrace-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example #7: Client and Server with asynchronous invocation (client-side)</a></li></ul>
</li><li><a shape="rect" href="#UsingApacheHTrace-DistributedTracingApacheHTraceandJAX-WSsupport">Distributed Tracing Apache HTrace and JAX-WS support</a></li><li><a shape="rect" href="#UsingApacheHTrace-PropagatingTraceDetailsToLogs">Propagating Trace Details To Logs</a></li><li><a shape="rect" href="#UsingApacheHTrace-FutureWork">Future Work</a></li></ul>
</div><h1 id="UsingApacheHTrace-Overview">Overview</h1><p><a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> is a tracing framework intended for use with distributed systems written in java. Since version <strong>3.1.3</strong>, Apache CXF fully supports integration with <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a>, both on client side and server side. This section gives a complete overview on how distributed tracing support is supported in JAX-RS applications built on top of Apache CXF.</p><h1 id="UsingApacheHTrace-DistributedTracinginNutshell">Distributed Tracing in Nutshell</h1><p>Distributed tracing, first described by Google in <a shape="rect" class="external-link" href="http://research.google.com/pubs/pub36356.html" rel="nofollow">Dapper, a Large-Scale Distributed Systems Tracing Infrastructure</a> paper became increasingly important topic these days. With
microservices (aka SOA) gaining more and more adoption, the typical applications are built using dozens or even hundreds of small, distributed pieces. The end-to-end traceability of the requests (or any kind of work performed on user's behalf) is hard task to accomplish, particularly taking into account asyncronous or/and concurrent invocations. <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> is inspired by <a shape="rect" class="external-link" href="http://research.google.com/pubs/pub36356.html" rel="nofollow">Dapper, a Large-Scale Distributed Systems Tracing Infrastructure</a> paper and essentially is a full-fledged distributed tracing framework.</p><p>Distributed tracing is additional instrumentation layer on top of new or existing applications. In terms of distributed tracing, <strong>span</strong> represents a basic unit of work. For example, executing database query is a <strong>span</strong>. <strong>Spans</strong>
are identified by a unique 128-bit ID. <strong>Spans</strong> also have other data, such as <strong>descriptions</strong>, <strong>timelines</strong>,<strong> key-value annotations</strong>, the <strong>ID</strong> of the <strong>span</strong> that caused them (parent), and <strong>process/tracer</strong> ID’s (normally IP address and process name). Spans are started and stopped, and they keep track of their timing information. Once <strong>span</strong> is created, it should be stopped at some point in the future. In turn, <strong>trace</strong> is a set of spans forming a tree-like structure. For example, if you are running a JAX-RS service, a trace might be formed by a <strong>PUT</strong> request and downstream work.</p><p>From implementation perspective, and in context of Java applications, <strong>spans</strong> are attached to their threads (in general, thread which created the <strong>span</strong> should close it). However it is possible to transfer <strong>spans</str
ong> from thread to thread in order to model a complex execution flows. It is also possible to have many <strong>spans</strong> in the same thread, as long as they are properly created and closed. In the next sections we are going to see the examples of that.</p><p>Another two important concepts in context of distributed tracing are <strong>span receivers</strong> and <strong>samplers</strong>. Essentially, all spans (including start/stop time, key/value annotations, timelines, ..) should be persisted (or collected) somewhere. <strong>Span receiver</strong> is a collector within a process that is the destination of <strong>spans</strong> when a trace is running (it could be a console, local file, data store, ...). <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> provides span receivers for <a shape="rect" class="external-link" href="http://hbase.apache.org">Apache HBase</a>, <a shape="rect" class="external-link" href="https
://flume.apache.org/">Apache Flume</a> and <a shape="rect" class="external-link" href="http://zipkin.io/" rel="nofollow">Twitter Zipkin</a>. From other side, <strong>samplers</strong> allow to control the frequency of the tracing (all the time, never, probability driven, ...). Using the <strong>sampler</strong> is the way to minimize tracing overhead (or just amount of traces) by limiting them to particular conditions.</p><h1 id="UsingApacheHTrace-DistributedTracinginApacheCXFusingApacheHTrace">Distributed Tracing in Apache CXF using Apache HTrace</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. As it was just mentioned before, distributed tracing is an essential technique to monitor the application as whole, breaking the req
uest 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 <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> (<strong>4.x+</strong> release branch) only in JAX-RS 2.x applications. From high-level prospective, it consists of three main parts:</p><ul style="list-style-type: square;"><li><strong>TracerContext</strong> (injectable through <strong>@Context</strong> annotation)</li><li><strong>HTraceProvider</strong> (server-side JAX-RS provider) and <strong>HTraceClientProvider</strong> (client-side JAX-RS provider)</li><li><strong>HTraceFeature</strong> (server-side <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> feature to simplify <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace
</a> configuration and integration)</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 used internally by <strong>HTraceProvider</strong> and <strong>HTraceClientProvider</strong>, but are configurable. The default header names are declared in the TracerHeaders class:</p><ul style="list-style-type: square;"><li><strong>X-Span-Id</strong>: contains a current span ID</li></ul><p>By default, <strong>HTraceProvider</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, just registering the <strong>HTraceClientProvider</strong> on the client and <strong>HTraceProvider</strong> on the server is enough to have tracing context to be properly passed ev
erywhere. The only configuration part which is necessary are <strong>span receiver(s)</strong> and <strong>sampler</strong>(s).</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="external-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="UsingApacheHTrace-ConfiguringClientconfigure.client">Configuring Client <span class="confluence-anchor-link" id="UsingApacheHTrace-configure.client"></span></h1><p>There are a couple of ways the JAX-RS client could be configured, depending on the client im
plementation. <a shape="rect" href="http://cxf.apache.org/">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 Map<String, String> properties = new HashMap<String, String>();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final Map<String, String> properties = new HashMap<String, String>();
properties.put(Tracer.SPAN_RECEIVER_CLASSES_KEY, ...);
properties.put(Tracer.SAMPLER_CLASSES_KEY, ...);
@@ -153,7 +153,7 @@ final Response response = WebClient
.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 Map<String, String> properties = new HashMap<String, String>();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final Map<String, String> properties = new HashMap<String, String>();
properties.put(Tracer.SPAN_RECEIVER_CLASSES_KEY, ...);
properties.put(Tracer.SAMPLER_CLASSES_KEY, ...);
@@ -177,11 +177,11 @@ final Response response = client
.accept(MediaType.APPLICATION_JSON)
.get();</pre>
</div></div><h3 id="UsingApacheHTrace-Configuringtracingheadernames">Configuring tracing header names</h3><p>To change the default HTTP header names, used to transfer the tracing context from client to server, it is enough to define one property: <strong>TracerHeaders.HEADER_SPAN_ID</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 ClientConfiguration config = WebClient.getConfig(client);
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final ClientConfiguration config = WebClient.getConfig(client);
config.getRequestContext().put(TracerHeaders.HEADER_SPAN_ID, "CUSTOM_HEADER_SPAN_ID");
</pre>
</div></div><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>It is very important to keep client and server HTTP headers configuration in sync, otherwise the server won't be able to establish the current tracing context properly.</p></div></div><h1 id="UsingApacheHTrace-ConfiguringServerconfigure.server">Configuring Server <span class="confluence-anchor-link" id="UsingApacheHTrace-configure.server"></span></h1><p>Server configuration is a bit simpler than the client one thanks to the feature class available, <strong>HTraceFeature</strong>. Depending on the way the <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="co
deContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@ApplicationPath("/")
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@ApplicationPath("/")
public class CatalogApplication extends Application {
@Override
public Set<Object> getSingletons() {
@@ -204,7 +204,7 @@ public class CatalogApplication extends
}
}</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 Map<String, String> properties = new HashMap<String, String>();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final Map<String, String> properties = new HashMap<String, String>();
properties.put(Tracer.SPAN_RECEIVER_CLASSES_KEY, ...);
properties.put(Tracer.SAMPLER_CLASSES_KEY, ...);
@@ -213,7 +213,7 @@ factory.setFeatures(Arrays.< Feature
...
return factory.create();</pre>
</div></div><p>Once the <strong>span receiver(s)</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><h3 id="UsingApacheHTrace-Configuringtracingheadernames.1">Configuring tracing header names</h3><p>As with the client, to change the default HTTP header names, used to establish the tracing context on the server, it is enough to define single property: <strong>TracerHeaders.HEADER_SPAN_ID</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 Map<String, Object> headers = new HashMap<String, Object>();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final Map<String, Object> headers = new HashMap<String, Object>();
headers.put(TracerHeaders.HEADER_SPAN_ID, "CUSTOM_HEADER_SPAN_ID");
final JAXRSServerFactoryBean sf = new JAXRSServerFactoryBean();
@@ -221,7 +221,7 @@ sf.setProperties(headers);
...
sf.create();</pre>
</div></div><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>It is very important to keep client and server HTTP headers configuration in sync, otherwise the server won't be able to establish the current tracing context properly.</p></div></div><h1 id="UsingApacheHTrace-DistributedTracingInAction:UsageScenarios">Distributed Tracing In Action: Usage Scenarios</h1><p>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="using-apache-htrace.html">Configuring Client</a> and <a shape="rect" href="using-apache-htrace.html">Configuring Server</a> secti
ons above).</p><h2 id="UsingApacheHTrace-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>HTraceClientProvider</strong>  and <strong>HTraceProvider</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 } )
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection<Book> getBooks() {
return Arrays.asList(
@@ -229,13 +229,13 @@ public Collection<Book> getBooks()
);
}</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
+<pre class="brush: java; gutter: false; theme: Default" 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 process name <strong><span class="label label-default service-filter-label service-tag-filtered">jaxrsclient/192.168.0.100</span></strong>) and consequent invocation of the service on the server side (process name<strong> <span class="label label-default service-filter-label">jaxrsserver/192.168.0.100</span></strong>) is going to generate the following sample traces:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-apache-htrace.data/image2015-9-13%2016:17:53.png"></span></p><h2 id="UsingApacheHTrace-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 pane
l 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 } )
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection<Book> getBooks(@Context final TracerContext tracer) throws Exception {
try(final TraceScope scope = tracer.startSpan("Calling External System")) {
@@ -248,7 +248,7 @@ public Collection<Book> getBooks(@
}
}</pre>
</div></div><p>The actual invocation of the request by the client (with process name <strong><span class="label label-default service-filter-label service-tag-filtered">jaxrsclient/192.168.0.100</span></strong>) and consequent invocation of the service on the server side (process name<strong> <span class="label label-default service-filter-label">jaxrsserver/192.168.0.100</span></strong>) is going to generate the following sample traces:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-apache-htrace.data/image2015-9-13%2017:5:12.png"></span></p><h2 id="UsingApacheHTrace-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="co
deContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection<Book> getBooks(@Context final TracerContext tracer) throws Exception {
tracer.timeline("Preparing Books");
@@ -260,7 +260,7 @@ public Collection<Book> getBooks(@
);
}</pre>
</div></div><p>The actual invocation of the request by the client (with process name <strong><span class="label label-default service-filter-label service-tag-filtered">jaxrsclient/192.168.0.100</span></strong>) and consequent invocation of the service on the server side (process name<strong> <span class="label label-default service-filter-label">jaxrsserver/192.168.0.100</span></strong>) is going to generate the following sample traces:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-apache-htrace.data/image2015-9-14%2021:4:9.png"></span></p><h2 id="UsingApacheHTrace-Example#4:ClientandServerwithannotatedtrace(key/value)">Example #4: Client and Server with annotated trace (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" styl
e="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection<Book> getBooks(@Context final TracerContext tracer) throws Exception {
final Collection<Book> books = Arrays.asList(
@@ -271,7 +271,7 @@ public Collection<Book> getBooks(@
return books;
}</pre>
</div></div><p>The actual invocation of the request by the client (with process name <strong><span class="label label-default service-filter-label service-tag-filtered">jaxrsclient/192.168.0.100</span></strong>) and consequent invocation of the service on the server side (process name<strong> <span class="label label-default service-filter-label">jaxrsserver/192.168.0.100</span></strong>) is going to generate the following sample server trace properties:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-apache-htrace.data/image2015-9-14%2021:11:56.png"></span></p><h2 id="UsingApacheHTrace-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 } )
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection<Book> getBooks(@Context final TracerContext tracer) throws Exception {
final Future<Book> book1 = executor.submit(
@@ -301,7 +301,7 @@ public Collection<Book> getBooks(@
return Arrays.asList(book1.get(), book2.get());
}</pre>
</div></div><p>The actual invocation of the request by the client (with process name <strong><span class="label label-default service-filter-label service-tag-filtered">jaxrsclient/192.168.0.100</span></strong>) and consequent invocation of the service on the server side (process name<strong> <span class="label label-default service-filter-label">jaxrsserver/192.168.0.100</span></strong>) is going to generate the following sample traces:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-apache-htrace.data/image2015-9-15%2020:44:20.png"></span></p><h2 id="UsingApacheHTrace-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 a
nd 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 } )
+<pre class="brush: java; gutter: false; theme: Default" 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<Future<Void>>() {
@@ -326,7 +326,7 @@ public void getBooks(@Suspended final As
});
}</pre>
</div></div><p>The actual invocation of the request by the client (with process name <strong><span class="label label-default service-filter-label service-tag-filtered">jaxrsclient/192.168.0.100</span></strong>) and consequent invocation of the service on the server side (process name<strong> <span class="label label-default service-filter-label">jaxrsserver/192.168.0.100</span></strong>) is going to generate the following sample traces:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-apache-htrace.data/image2015-9-15%2021:26:5.png"></span></p><h2 id="UsingApacheHTrace-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="codeCont
ent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection<Book> getBooks() {
return Arrays.asList(
@@ -334,14 +334,14 @@ public Collection<Book> getBooks()
);
}</pre>
</div></div><p>While the JAX-RS client 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<Response> future = client
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final Future<Response> 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 process name <strong><span class="label label-default service-filter-label service-tag-filtered">jaxrsclient/192.168.0.100</span></strong>) and consequent invocation of the service on the server side (process name<strong> <span class="label label-default service-filter-label">jaxrsserver/192.168.0.100</span></strong>) is going to generate the following sample traces:</p><p><span class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image" height="250" src="using-apache-htrace.data/image2015-9-16%2021:9:56.png"></span></p><h1 id="Using
ApacheHTrace-DistributedTracingApacheHTraceandJAX-WSsupport">Distributed Tracing Apache HTrace 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 <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> API directly (the JAX-WS integration is going to be enhanced in the nearest future). Essentially, from the server-side prospective the in/out interceptors, <strong>HTraceStartInterceptor</strong> and <strong>HTraceStopInterceptor </strong>respectively, should be configured as part of interceptor chains. The <strong>span</strong> receiver should be configured manually though, using <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> API, 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 Map<String, String> properties = new HashMap<String, String>();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final Map<String, String> properties = new HashMap<String, String>();
final HTraceConfiguration conf = HTraceConfiguration.fromMap(properties);
Trace.addReceiver(new StandardOutSpanReceiver(conf));
@@ -352,14 +352,14 @@ sf.getOutInterceptors().add(new HTraceSt
...
sf.create();</pre>
</div></div><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>Configuring right phases for interceptors is very important. The recommended phase for in-interceptor is <strong>PRE_INVOKE</strong> while for out-interceptor is <strong>PRE_MARSHAL</strong>. If wrong phases are being used, response or/and request headers could be ignored or not processed.</p></div></div><p>Similarly to the server-side, client-side needs own set of out/in interceptors, <strong>HTraceClientStartInterceptor</strong> and <strong>HTraceClientStopInterceptor</strong>. Please notice the difference from server-side: <strong>HTraceClientStartInterceptor</strong> becomes out-interceptor while <strong>HTraceClientStopInterceptor</strong> becomes in-interceptor. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div cl
ass="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence" style="font-size:12px;">JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();
...
factory.getOutInterceptors().add(new HTraceClientStartInterceptor(sampler));
factory.getInInterceptors().add(new HTraceClientStopInterceptor());
...
factory.create();</pre>
</div></div><h1 id="UsingApacheHTrace-PropagatingTraceDetailsToLogs">Propagating Trace Details To Logs</h1><p>In order to have better correlation between ongoing traces and logs, <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> since <strong>3.1.11</strong> / <strong>3.2.0</strong> releases distributes a helpful extension for <a shape="rect" class="external-link" href="https://logback.qos.ch/" rel="nofollow">Logback</a> users, <strong>LogbackSpanConverter</strong>. This converter can be used to complement log records with current trace details, such as tracer id and span id. For example, here is a simple <strong>logback.xml</strong> configuration file.</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;"><?xml version="1.0" encoding="UTF-8"?>
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="5 seconds">
<conversionRule conversionWord="trace" converterClass="org.apache.cxf.tracing.htrace.ext.LogbackSpanConverter" />
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
@@ -372,7 +372,7 @@ factory.create();</pre>
</root>
</configuration></pre>
</div></div><p>In this case the tracing details will be propagated to each log record in following format: <strong><tracer_id>, span: <span id></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;">[INFO] [-, -] 2017-03-11 14:40:13.603 org.eclipse.jetty.server.Server Started @2731ms
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">[INFO] [-, -] 2017-03-11 14:40:13.603 org.eclipse.jetty.server.Server Started @2731ms
[INFO] [tracer-server/192.168.0.101, span: 6d3e0d975d4c883cce12aee1fd8f3e7e] 2017-03-11 14:40:24.013 com.example.rs.PeopleRestService Getting all employees
[INFO] [tracer-server/192.168.0.101, span: 6d3e0d975d4c883c7592f4c2317dec22] 2017-03-11 14:40:28.017 com.example.rs.PeopleRestService Looking up manager in the DB database</pre>
</div></div><p>The special <strong>[-, -]</strong> placeholder indicates that no trace details are being available at the moment of logging the record.</p><h1 id="UsingApacheHTrace-FutureWork">Future Work</h1><p>The <a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> is very proud to offer <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> integration. At the current stage, it was a conscious decision to keep the minimal API and provide the set of necessary features only. However, there is a strong commitment to evolve not only <a shape="rect" class="external-link" href="http://htrace.incubator.apache.org/index.html">Apache HTrace</a> integration, but the distributed tracing support in general.</p></div>
Modified: websites/production/cxf/content/docs/using-cxf-and-cdi-11-jsr-346.html
==============================================================================
--- websites/production/cxf/content/docs/using-cxf-and-cdi-11-jsr-346.html (original)
+++ websites/production/cxf/content/docs/using-cxf-and-cdi-11-jsr-346.html Wed Sep 13 15:05:52 2017
@@ -32,8 +32,8 @@
<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 src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -118,11 +118,11 @@ Apache CXF -- Using CXF and CDI 1.1 (JSR
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1 id="UsingCXFandCDI1.1(JSR-346)-Introduction">Introduction </h1><p>The JAX-RS 2.0 specification (JSR-339) mandates the support of CDI 1.1 (JSR-346) and Apache CXF starting from the version 3.0 introduces the initial support of this feature. As the starting point, the emphasis has been done on supporting embedded Jety 8/9 and Tomcat 7/8 containers as primary deployment (though other application servers will be supported in the future). </p><h1 id="UsingCXFandCDI1.1(JSR-346)-Architectureanddesign">Architecture and design </h1><p>At the moment, the integration of Apache CXF and CDI revolves around two key components, which reside in the new module called <strong>cxf-integration-cdi</strong></p><ul><li><strong>CXFCdiServlet</strong> servlet</li><li><strong>JAXRSCdiResourceExtension</strong> portable CDI extension</li></ul><p>The fact of including <strong>cxf-integration-cdi</strong> as a dependency allows  <strong>JAXRSCdiResourceExtens
ion</strong>  portable CDI extension to be discovered by CDI container. The  <strong>JAXRSCdiResourceExtension</strong> creates the instance of the <strong>Bus</strong> and registers it with <strong>BeanManager</strong>. From this point, the  <strong>Bus</strong> instance is a regular CDI bean (with <span><strong>@</strong><span><strong>Application</strong> scope)</span></span> available for injection. This instance of the  <strong>Bus</strong> is being injected into <strong>CXFCdiServlet</strong> servlet once it is initialized by servlet container.</p><p>Depending on the design, <strong>JAXRSCdiResourceExtension</strong> may use zero-based configuration approach or rely on particular JAX-RS <strong>Application</strong> instances. The <strong>org.apache.cxf.cdi.CXFCdiServlet</strong> should be configured as well (more examples for programmatic and WAR scenarios below).</p><h1 id="UsingCXFandCDI1.1(JSR-346)-Zero-basedConfiguration">Ze
ro-based Configuration</h1><p>If the Apache CXF application contains only one single instance of JAX-RS <strong>Application</strong> (annotated with <strong>@ApplicationPath</strong>) with no singletons and classes defined, the following rules are being applied by <strong>JAXRSCdiResourceExtension</strong> in order to configure and publish the configured JAX-RS resources:</p><ul><li>the instance of the JAX-RS <strong>Application</strong> (annotated with <strong>@ApplicationPath</strong>) is being created and registered with <strong>BeanManager</strong></li><li>all instances of the discovered JAX-RS <strong>providers </strong>(annotated with <strong>@Provider</strong>) are being created and registered with <strong>BeanManager</strong></li><li>all instances of the discovered JAX-RS <strong>resources</strong> (annotated with <strong>@Path</strong>) are being created and registered with <strong>BeanManager</strong></li></ul><p>Lastly, the instance of the <strong>JAXRSServerFactoryBean</
strong> is being created and configured with all service beans and providers discovered before. Additionally, the providers are enriched with the services for <strong>javax.ws.rs.ext.MessageBodyReader</strong> and <strong>javax.ws.rs.ext.MessageBodyWriter</strong>, loaded via <strong>ServiceLoader</strong>. From this moment, Apache CXF application is ready to serve the requests. The quick example is shown below.</p><p>The empty JAX-RS <strong>Application</strong>:</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("/api")
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@ApplicationPath("/api")
public class BookStoreApplication extends Application {
}</pre>
</div></div><p>And one JAX-RS resource:</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;">@Path("/bookstore/")
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Path("/bookstore/")
public class BookStore {
@Inject private BookStoreService service;
@@ -134,7 +134,7 @@ public class BookStore {
}
}</pre>
</div></div><h1 id="UsingCXFandCDI1.1(JSR-346)-CustomizedConfiguration">Customized Configuration</h1><p>If the Apache CXF application contains one or more instances of JAX-RS <strong>Application</strong> (annotated with <strong>@ApplicationPath</strong>) with singletons or classes defined, the following rules are being applied by <strong>JAXRSCdiResourceExtension</strong> in order to configure and publish the configured JAX-RS resources:</p><ul><li>the instance of each JAX-RS <strong>Application</strong> (annotated with <strong>@ApplicationPath</strong>) is being created and registered with <strong>BeanManager</strong></li><li>for each JAX-RS <strong>Application</strong> instance created before, the instance of the <strong>JAXRSServerFactoryBean</strong> is being created and configured in a way that application's singletons/classes are being splitted to providers (annotated with <strong>@Provider</strong>), service beans (annotated with <strong>@Path</strong>) and features (imp
lementation of <strong>org.apache.cxf.feature.Feature</strong>)<strong> </strong></li></ul><p>From this moment, Apache CXF application is ready to serve the requests. The quick example is shown below.</p><p>The configured JAX-RS <strong>Application</strong>:</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("/custom")
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@ApplicationPath("/custom")
public class BookStoreCustomApplication extends Application {
@Inject private BookStore bookStore;
@@ -148,7 +148,7 @@ public class BookStoreCustomApplication
}
}</pre>
</div></div><p>And one JAX-RS resource:</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;">@Path("/bookstore/")
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Path("/bookstore/")
public class BookStore {
@Inject private BookStoreService service;
@@ -160,7 +160,7 @@ public class BookStore {
}
}</pre>
</div></div><h1 id="UsingCXFandCDI1.1(JSR-346)-DeployingwithembeddedJetty8/9(programmaticconfiguration)">Deploying with embedded Jetty 8/9 (programmatic configuration)</h1><p>With <strong>Jetty 8/9</strong> it possible to create fully embeddable REST / JAX-RS servers without <strong>web.xml</strong> or <strong>WAR</strong> files involved. For Apache CXF applications which are using CDI 1.1, the <strong>CXFCdiServlet</strong> servlet should be used as a starting point. Following example demonstrates the necessary configuration points in order to create embedded <strong>Jetty 8/9</strong> instance. As a CDI 1.1 implementation, <strong>JBoss Weld 2.0</strong> is being used.</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;">System.setProperty("java.naming.factory.url", "org.eclipse.jetty.jndi");
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">System.setProperty("java.naming.factory.url", "org.eclipse.jetty.jndi");
System.setProperty("java.naming.factory.initial", "org.eclipse.jetty.jndi.InitialContextFactory");
// Register and map the dispatcher servlet
@@ -174,7 +174,7 @@ context.addServlet(servletHolder, "/rest
server.setHandler(context);
server.start();</pre>
</div></div><p>This code snippet is enough to trigger the CDI portable extension discovery, to perform the configuration (depending on JAX-RS <strong>Applications</strong> present) and to wire up all defined dependencies together.</p><h1 id="UsingCXFandCDI1.1(JSR-346)-DeployingwithembeddedJetty8/9(WAR-baseddeployment)">Deploying with embedded Jetty 8/9 (WAR-based deployment) </h1><p>Another option to deploy Apache CXF application with CDI 1.1 support and embedded <strong>Jetty 8/9</strong> is by using <strong>web.xml</strong> descriptor and WAR-like deployment structure. In this case, the Apache CXF application needs to declare <strong>CXFCdiServlet</strong> servlet (and its mappings) and, if required, CDI-specific listeners (in the example below the <strong>JBoss Weld 2.0</strong> is being used as CDI 1.1 container).</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;"><web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<listener>
@@ -200,7 +200,7 @@ server.start();</pre>
</resource-env-ref>
</web-app></pre>
</div></div><p>The server initialization in this case looks simpler.</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;">System.setProperty("java.naming.factory.url", "org.eclipse.jetty.jndi");
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">System.setProperty("java.naming.factory.url", "org.eclipse.jetty.jndi");
System.setProperty("java.naming.factory.initial", "org.eclipse.jetty.jndi.InitialContextFactory");
final Server server = new Server(<port>);
@@ -214,7 +214,7 @@ handlers.setHandlers(new Handler[] {cont
server.setHandler(handlers);
server.start();</pre>
</div></div><p>Please notice, usage of Jetty-specific server classes ("org.eclipse.jetty.servlet.ServletContextHandler.Decorator") is very important to allow CDI 1.1 injections (backed by <strong>JBoss Weld 2.0</strong>) to work seamlessly across servlets / listeners / filters. It is not stricktly necessary for Apache CXF (everything will work as expected) but complex applications would definitely benefit from that.</p><h1 id="UsingCXFandCDI1.1(JSR-346)-DeployingwithembeddedTomcat7/8(WAR-baseddeployment)">Deploying with embedded Tomcat 7/8 (WAR-based deployment) </h1><p>In case of embedded Tomcat 7/8, Apache CXF application with CDI 1.1 support could be deployed with <strong>web.xml</strong> descriptor and WAR-like deployment structure, similarly to Jetty 8/9 WAR-based deployment. Apache CXF application needs to declare <strong>CXFCdiServlet</strong> servlet (and its mappings) and, if required, CDI-specific listeners (in the example below the <strong>JBoss Weld 2.0</strong
> is being used as CDI 1.1 container).</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;"><web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<listener>
@@ -240,7 +240,7 @@ server.start();</pre>
</resource-env-ref>
</web-app></pre>
</div></div><p>Tomcat 7/8 server has a different API, by still quite simple initialization procedure.</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 Tomcat server = new Tomcat();
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">final Tomcat server = new Tomcat();
server.setPort(<port>);
final File base = createTemporaryDirectory();