Author: buildbot
Date: Fri Jan 11 14:56:46 2019
New Revision: 1038852
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-filters.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jax-rs-filters.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-filters.html (original)
+++ websites/production/cxf/content/docs/jax-rs-filters.html Fri Jan 11
14:56:46 2019
@@ -117,22 +117,22 @@ Apache CXF -- JAX-RS Filters
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div
id="ConfluenceContent"><p> </p><p> </p><p> </p><p> </p><p> <span
style="font-size:2em;font-weight:bold">JAX-RS Filters</span>
+<div id="ConfluenceContent"><p><span
style="font-size:2em;font-weight:bold">JAX-RS Filters</span>
- </p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1524513401082 {padding: 0px;}
-div.rbtoc1524513401082 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1524513401082 li {margin-left: 0px;padding-left: 0px;}
+ </p><p> </p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1547218568744 {padding: 0px;}
+div.rbtoc1547218568744 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1547218568744 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1524513401082">
+/*]]>*/</style></p><div class="toc-macro rbtoc1547218568744">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFilters-Filters">Filters</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFilters-DifferencebetweenJAXRSfiltersandCXFinterceptors">Difference
between JAXRS filters and CXF interceptors</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSFilters-Overridingrequestandresponseproperties">Overriding request
and response properties</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSFilters-OverridingHTTPmethod">Overriding HTTP
method</a></li><li><a shape="rect"
href="#JAX-RSFilters-OverridingrequestURI,queryandheaders">Overriding request
URI, query and headers</a></li><li><a shape="rect"
href="#JAX-RSFilters-Overridingresponsestatuscodeandheaders">Overriding
response status code and headers</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSFilters-IgnoringJAXRSMessageBodyWriters">Ignoring JAXRS
MessageBodyWriters</a></li><li><a shape="rect"
href="#JAX-RSFilters-Custominvokers">Custom invokers</a></li></ul>
</div><h1 id="JAX-RSFilters-Filters">Filters</h1><p>Often it's necessary to
pre- or post-process some requests according to a number of requirements.<br
clear="none"> For example, a request like</p><p>GET /resource?_type=xml is
supported by a CXF specific RequestPreprocessor code which modifies an input
message <br clear="none"> by updating one of its headers.</p><p>A standard
mechanism for updating the request or response properties is to use JAX-RS 2.0
ContainerRequestFilter or
ContainerResponseFilter.</p><p>ContainerRequestFilters with a @PreMatching
annotation are run before the JAX-RS resource selection process starts.
PreMatching filters should be used to modify request URI or headers or input
stream. Post-matching filters are run just before a selected resource method is
executed.</p><p>Multiple ContainerRequestFilter and ContainerResponseFilter
filters can be ordered using a @Priority annotation.</p><p> </p><p>The
implementations can be registered like any other type of
providers :</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<jaxrs:server id="customerService" address="/">
<jaxrs:serviceBeans>
<bean class="org.CustomerService" />
@@ -148,7 +148,7 @@ div.rbtoc1524513401082 li {margin-left:
</beans>
</pre>
</div></div><h2
id="JAX-RSFilters-DifferencebetweenJAXRSfiltersandCXFinterceptors">Difference
between JAXRS filters and CXF interceptors</h2><p>JAXRS runtime flow is mainly
implemented by a pair of 'classical' CXF interceptors. JAXRSInInterceptor is
currently at Phase.UNMARSHAL (was at Phase.PRE_STREAM before CXF 2.2.2) phase
while JAXRSOutInterceptor is currently at Phase.MARSHAL phase.</p><p>JAXRS
filters can be thought of as additional handlers. JAXRSInInterceptor deals with
a chain of Pre and Post Match ContainerRequestFilters, just before the
invocation. JAXRSOutInterceptor deals with a chain of ContainerResponseFilters,
just after the invocation but before message body writers get their
chance.</p><p>Sometimes you may want to use CXF interceptors rather than
writing JAXRS filters. For example, suppose you combine JAXWS and JAXRS and you
need to log only inbound or outbound messages. You can reuse the existing CXF
interceptors :</p><div class="code panel pdl" style="border-widt
h: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<bean id="logInbound"
class="org.apache.cxf.interceptor.LoggingInInterceptor"/>
<bean id="logOutbound"
class="org.apache.cxf.interceptor.LoggingOutInterceptor"/>
@@ -173,12 +173,12 @@ div.rbtoc1524513401082 li {margin-left:
</beans>
</pre>
</div></div><p>Reusing other CXF interceptors/features such as GZIP handlers
can be useful too.</p><h1
id="JAX-RSFilters-Overridingrequestandresponseproperties">Overriding request
and response properties</h1><p>Now and then one needs to overwrite various
request and response properties like HTTP method or request URI, <br
clear="none"> response headers or status codes and even the request or response
body. JAX-RS Response may be used to specify custom status and response headers
but it might be intrusive to add it to method signatures.</p><p>Using filters
and interceptors makes it possible to override all the needed request/response
properties.</p><h2 id="JAX-RSFilters-OverridingHTTPmethod">Overriding HTTP
method</h2><p>Use @PreMatching ContainerRequestFilter or register a custom CXF
in intrerceptor filter which will replace the current method value keyed by <br
clear="none"> Message.HTTP_REQUEST_METHOD in a given Message.</p><h2
id="JAX-RSFilters-OverridingrequestURI,queryandheader
s">Overriding request URI, query and headers</h2><p>One can do it either from
@PreMatching ContainerRequestFilter or CXF input interceptor (registered at the
early phase like USER_STREAM), for example :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">String s = m.get(Message.REQUEST_URI);
+<pre class="brush: java; gutter: false; theme: Default">String s =
m.get(Message.REQUEST_URI);
s += "/data/";
m.put(Message.REQUEST_URI, s);
</pre>
</div></div><p>If the updated Request URI has a new query string, then you
also need to update a Message.QUERY_STRING property.</p><p>Similarly, one can
update request HTTP headers, by modifying a Message.REQUEST_HEADERS Message
object which is a Map containing String and List of Strings entries.</p><h2
id="JAX-RSFilters-Overridingresponsestatuscodeandheaders">Overriding response
status code and headers</h2><p>It is assumed here a user prefers not to use
explicit Response objects in the application code.<br clear="none"> This can be
done either from ContainerResponseFilter or CXF output interceptor (phase like
MARSHALL will do), for example this code will work for both JAXRS and JAXWS
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import java.util.Map;
+<pre class="brush: java; gutter: false; theme: Default">import java.util.Map;
import java.util.TreeMap;
import org.apache.cxf.message.Message;
@@ -202,10 +202,10 @@ public class CustomOutInterceptor extend
}
</pre>
</div></div><p>At the moment it is not possible to override a response status
code from a CXF interceptor running before JAXRSOutInterceptor, like
CustomOutInterceptor above, which will be fixed.<br clear="none"> The only
option at the moment is to use a custom ResponseHandler which will replace the
current Response object with another one containing the required status.</p><h1
id="JAX-RSFilters-IgnoringJAXRSMessageBodyWriters">Ignoring JAXRS
MessageBodyWriters</h1><p>In some cases you may want to have a JAXRS Response
entity which a given filter has produced to be directly written to the output
stream. For example, a CXF JAXRS WADLGenerator filter produces an XML content
which does not have to be serialized by JAXRS MessageBodyWriters. If you do
need to have the writers ignored then set the following property on the current
exchange in the custom handler :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">message.getExchange().put("ignore.message.writers",
true);
+<pre class="brush: java; gutter: false; theme:
Default">message.getExchange().put("ignore.message.writers", true);
</pre>
</div></div><h1 id="JAX-RSFilters-Custominvokers">Custom
invokers</h1><p><strong>Note</strong> This feature is available starting from
CXF 2.2.2</p><p>Using custom JAXR-RS invokers is yet another way to pre or post
process a given invocation. For example, this <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/CustomJAXRSInvoker.java";>invoker</a>
does a security check before delegating to the default JAXRS invoker. A custom
invoker, like a request filter, has the access to all the information
accumulated during the processing of a given call, but additionally, it can
also check the actual method parameter values.</p><p>Custom invokers can be
registered like this :</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans>
+<pre class="brush: java; gutter: false; theme: Default"><beans>
<jaxrs:server address="/">
<jaxrs:invoker>
