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();
