Author: buildbot
Date: Thu May 11 01:42:50 2023
New Revision: 1083174
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
websites/production/cxf/content/docs/jax-rs-multiparts.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified:
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
==============================================================================
---
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
(original)
+++
websites/production/cxf/content/docs/asynchronous-client-http-transport.html
Thu May 11 01:42:50 2023
@@ -107,7 +107,7 @@ Apache CXF -- Asynchronous Client HTTP T
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1
id="AsynchronousClientHTTPTransport-AsynchronousClientHTTPTransport">Asynchronous
Client HTTP Transport</h1><p>By default, CXF uses a transport based on the
in-JDK HttpURLConnection object to perform HTTP requests. The HttpURLConnection
object uses a blocking model for all IO operations which requires a per-thread
execution model. From a pure performance standpoint, this model generally
performs very well, but it does have problems scaling when many requests need
to be executed simultaneously.</p><p>Also, the JAX-WS specification allows for
generation of asynchronous methods on generated proxies as well as using
asynchronous methods on the Dispatch objects. These methods can take an
AsyncHandler object and return a polling Future object so applications do not
have to wait for the response. With the HttpURLConnection based transport, CXF
was forced to consume a background thread for each outstanding request.</p><h3
id="AsynchronousClientHTTPTransport-A
pacheHttpComponents4.x">Apache HttpComponents 4.x</h3><p>CXF also has an HTTP
client transport that is based on the <a shape="rect" class="external-link"
href="http://hc.apache.org/httpcomponents-asyncclient/index.html";>Apache HTTP
Components HttpAsyncClient</a> library. Its Maven artifactId is <span
style="line-height:
1.4285715;"><strong>cxf-rt-transports-http-hc</strong>.</span><span
style="line-height: 1.4285715;"> The HttpAsyncClient library uses a
non-blocking IO model. This allows many more requests to be outstanding without
consuming extra background threads. It also allows greater control over things
like Keep-Alive handling which is very difficult or impossible with the
HttpURLConnection based transport. However, the non-blocking model does not
perform quite as well as the blocking model for pure synchronous
request/response transactions.</span></p><p>By default, if the
<strong>cxf-rt-transports-http-hc</strong> module is found on the classpath,
CXF will use the <stro
ng>HttpAsyncClient </strong>based implementation for any Async calls, but will
continue to use the HttpURLConnection based transport for synchronous calls.
This allows a good balance of performance for the common synchronous cases with
scalability for the asynchronous cases. However, using a contextual property of
"use.async.http.conduit" and set to true/false, you can control whether the
async or blocking version is used. If "true", the HttpAsyncClient will be used
even for synchronous calls, if "false", asynchronous calls will rely on the
traditional method of using HTTPURLConnection along with a work queue to mimic
the asynchronicity.  And if TLSClientParameters sets an
SSLSocketFactory,  as SocketFactory class and SocketFactory#createSocket
methods in particular are inherently blocking and sockets instantiated in such
a way cannot be used for asynchronous, so this lead to use the
HttpURLConnection based transport.</p><p>Another reason to use the asynchronous
transport
is to use HTTP methods that HttpURLConnection does not support. For example,
the github.com REST API specifies the use of PATCH for some cases, but
HttpURLConnection rejects PATCH.</p><h3
id="AsynchronousClientHTTPTransport-ApacheHttpComponents5.x">Apache
HttpComponents 5.x</h3><p>Since <strong>3.4.6</strong>, CXF offers an HTTP
client transport that is based on <a shape="rect" class="external-link"
href="https://hc.apache.org/httpcomponents-client-5.1.x/index.html";>Apache
HttpComponents HttpClient 5</a> library, that supports synchronous,
asynchronous and reactive programming models. Its Maven artifactId is
<span><strong>cxf-rt-transports-http-hc5 </strong>and it serves as in-place
replacement for <strong>cxf-rt-transports-http-hc</strong> (but the usage of
those two transports together should be avoided).</span><span> </span></p><div
class="confluence-information-macro confluence-information-macro-warning"><span
class="aui-icon aui-icon-small aui-iconfont-error confluence-informat
ion-macro-icon"></span><div class="confluence-information-macro-body"><p>At
the moment,  <span><strong>cxf-rt-transports-http-hc5 </strong>transport
does not support OSGi based deployments</span></p></div></div><p>This client
transport supports HTTP/2.</p><h3
id="AsynchronousClientHTTPTransport-UsingtheHTTPComponents4.x/5.xTransportfromJavaCode">Using
the HTTP Components 4.x/5.x Transport from Java Code</h3><p>To force global
use of the HTTP Components transport, you can set a bus-level property:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<div id="ConfluenceContent"><h1
id="AsynchronousClientHTTPTransport-AsynchronousClientHTTPTransport">Asynchronous
Client HTTP Transport</h1><p>By default, CXF uses a transport based on the
in-JDK HttpURLConnection object to perform HTTP requests. The HttpURLConnection
object uses a blocking model for all IO operations which requires a per-thread
execution model. From a pure performance standpoint, this model generally
performs very well, but it does have problems scaling when many requests need
to be executed simultaneously.</p><p>Also, the JAX-WS specification allows for
generation of asynchronous methods on generated proxies as well as using
asynchronous methods on the Dispatch objects. These methods can take an
AsyncHandler object and return a polling Future object so applications do not
have to wait for the response. With the HttpURLConnection based transport, CXF
was forced to consume a background thread for each outstanding request.</p><h3
id="AsynchronousClientHTTPTransport-A
pacheHttpComponents4.x">Apache HttpComponents 4.x</h3><p>CXF also has an HTTP
client transport that is based on the <a shape="rect" class="external-link"
href="http://hc.apache.org/httpcomponents-asyncclient/index.html";>Apache HTTP
Components HttpAsyncClient</a> library. Its Maven artifactId is <span
style="line-height:
1.4285715;"><strong>cxf-rt-transports-http-hc</strong>.</span><span
style="line-height: 1.4285715;"> The HttpAsyncClient library uses a
non-blocking IO model. This allows many more requests to be outstanding without
consuming extra background threads. It also allows greater control over things
like Keep-Alive handling which is very difficult or impossible with the
HttpURLConnection based transport. However, the non-blocking model does not
perform quite as well as the blocking model for pure synchronous
request/response transactions.</span></p><p>By default, if the
<strong>cxf-rt-transports-http-hc</strong> module is found on the classpath,
CXF will use the <stro
ng>HttpAsyncClient </strong>based implementation for any Async calls, but will
continue to use the HttpURLConnection based transport for synchronous calls.
This allows a good balance of performance for the common synchronous cases with
scalability for the asynchronous cases. However, using a contextual property of
"use.async.http.conduit" and set to true/false, you can control whether the
async or blocking version is used. If "true", the HttpAsyncClient will be used
even for synchronous calls, if "false", asynchronous calls will rely on the
traditional method of using HTTPURLConnection along with a work queue to mimic
the asynchronicity.  And if TLSClientParameters sets an
SSLSocketFactory,  as SocketFactory class and SocketFactory#createSocket
methods in particular are inherently blocking and sockets instantiated in such
a way cannot be used for asynchronous, so this lead to use the
HttpURLConnection based transport.</p><p>Another reason to use the asynchronous
transport
is to use HTTP methods that HttpURLConnection does not support. For example,
the github.com REST API specifies the use of PATCH for some cases, but
HttpURLConnection rejects PATCH.</p><h3
id="AsynchronousClientHTTPTransport-ApacheHttpComponents5.x">Apache
HttpComponents 5.x</h3><p>Since <strong>3.4.6</strong>, CXF offers an HTTP
client transport that is based on <a shape="rect" class="external-link"
href="https://hc.apache.org/httpcomponents-client-5.1.x/index.html";>Apache
HttpComponents HttpClient 5</a> library, that supports synchronous,
asynchronous and reactive programming models. Its Maven artifactId is
<span><strong>cxf-rt-transports-http-hc5 </strong>and it serves as in-place
replacement for <strong>cxf-rt-transports-http-hc</strong> (but the usage of
those two transports together should be avoided).</span><span> </span></p><div
class="confluence-information-macro confluence-information-macro-warning"><span
class="aui-icon aui-icon-small aui-iconfont-error confluence-informat
ion-macro-icon"></span><div class="confluence-information-macro-body"><p>At
the moment,  <span><strong>cxf-rt-transports-http-hc5 </strong>transport
does not support OSGi based deployments</span></p></div></div><p>This client
transport supports HTTP/2 (when enabled using
<strong>org.apache.cxf.transports.http2.enabled</strong> property, see
<strong>Configuration</strong> section below).</p><h3
id="AsynchronousClientHTTPTransport-UsingtheHTTPComponents4.x/5.xTransportfromJavaCode">Using
the HTTP Components 4.x/5.x Transport from Java Code</h3><p>To force global
use of the HTTP Components transport, you can set a bus-level property:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"> Bus bus =
BusFactory.getDefaultBus();
// insist on the async connector to use PATCH
bus.setProperty(AsyncHTTPConduit.USE_ASYNC, Boolean.TRUE);
@@ -123,7 +123,7 @@ bp.getRequestContext().put(AsyncHTTPCond
<pre class="brush: java; gutter: false; theme: Default">Credentials creds =
new NTCredentials("username", "pswd", null, "domain");
bp.getRequestContext().put(Credentials.class.getName(), creds);
</pre>
-</div></div></li></ul><h3 id="AsynchronousClientHTTPTransport-Netty4.x">Netty
4.x</h3><p><br clear="none"></p><p>This client transport supports
HTTP/2.</p><h3
id="AsynchronousClientHTTPTransport-Configuration">Configuration</h3><p>The
Asynchronous HTTP Transport has several options that can set using Bus
properties or via the OSGi configuration services to control various aspects of
the underlying Apache HTTP Components HttpAsyncClient objects.</p><p>Settings
related to the underlying TCP socket (see <a shape="rect" class="external-link"
href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html";
rel="nofollow">java.net.Socket</a> for a definition of these values):</p><div
class="table-wrap"><table class="wrapped confluenceTable"><tbody><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.TCP_NODELAY
(Default true)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_KEEPALIVE</p><
/td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_LINGER</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_TIMEOUT</p></td></tr></tbody></table></div><p>Settings
related to Keep-Alive connection management:</p><div class="table-wrap"><table
class="wrapped confluenceTable"><colgroup span="1"><col span="1"><col
span="1"></colgroup><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.CONNECTION_TTL</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Maximum time a connection to
live(from creation to expiry)<span> </span>. Default is
60000.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><span>Maximum number of
connections opened in total. Default is 5000.</span></p></td></tr><tr><td cols
pan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_PER_HOST_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><span>Maximum number of
connections opened per host. Default is
1000.</span></p></td></tr></tbody></table></div><p>Settings related to
<strong>HTTP/2</strong> support (Apache CXF versions
<strong>4.0.2+</strong>/<strong>3.6.1+</strong>/<strong>3.5.7</strong>+/<strong>3.4.11+</strong>):</p><div
class="table-wrap"><table class="confluenceTable"><colgroup span="1"><col
span="1"><col span="1"><col span="1"></colgroup><tbody><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transports.http2.enabled</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>true | false</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Allows HTTP/2 protocol if
supported by the server. Default is
<strong>false</strong>.</p></td></tr></tbody></table></div><p>Settings related
to Apache HttpAsyncClient threads and
selectors:</p><div class="table-wrap"><table class="wrapped
confluenceTable"><colgroup span="1"><col span="1"><col
span="1"></colgroup><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.ioThreadCount</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Number of threads
HttpAsyncClient uses to process IO events. Default is "-1" which means one
thread per CPU core.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.interestOpQueued
<strong>(*)</strong></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>true/false for whether the interest ops are queues or
process directly.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.selectInterval</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Default 1000 ms. How often the
selector thread wakes up if there are no events to process additional things
like queue e
xpirations.</p></td></tr></tbody></table></div><p><strong>* </strong>-
for Apache HttpComponents 4.x only</p><p>Setting to control which conduit
is used</p><div class="table-wrap"><table class="wrapped
confluenceTable"><colgroup span="1"><col span="1"><col span="1"><col
span="1"></colgroup><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.usePolicy</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>ALWAYS, ASYNC_ONLY,
NEVER.</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Similar in
meaning to the "use.async.http.conduit" context property described above.
Whether to use the HttpAsyncClient: ALWAYS for both synchronous and
asynchronous calls, ASYNC_ONLY (default) for asynchronous calls only, NEVER
will use HTTPURLConnection for both types of
calls.</p></td></tr></tbody></table></div></div>
+</div></div></li></ul><h3 id="AsynchronousClientHTTPTransport-Netty4.x">Netty
4.x </h3><p>Apache CXF also offers an HTTP client transport that is based on
Netty 4.x. Its Maven artifactId is
<strong>cxf-rt-transports-http-netty-client</strong>. </p><p>This client
transport supports HTTP/2 (when enabled using
<strong>org.apache.cxf.transports.http2.enabled</strong> property, see
<strong>Configuration</strong> section below).</p><h3
id="AsynchronousClientHTTPTransport-Configuration">Configuration</h3><p>The
Asynchronous HTTP Transport has several options that can set using Bus
properties or via the OSGi configuration services to control various aspects of
the underlying Apache HTTP Components HttpAsyncClient objects.</p><p>Settings
related to the underlying TCP socket (see <a shape="rect" class="external-link"
href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html";
rel="nofollow">java.net.Socket</a> for a definition of these values):</p><div
class="table-wrap"><table class
="wrapped confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.TCP_NODELAY
(Default true)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_KEEPALIVE</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_LINGER</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.SO_TIMEOUT</p></td></tr></tbody></table></div><p>Settings
related to Keep-Alive connection management:</p><div class="table-wrap"><table
class="wrapped confluenceTable"><colgroup span="1"><col span="1"><col
span="1"></colgroup><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.CONNECTION_TTL</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Maximum time a connection to
live(from creation to expiry)<span> </span>. Default is 60000.</p></td>
</tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><span>Maximum number of
connections opened in total. Default is 5000.</span></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.MAX_PER_HOST_CONNECTIONS</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><span>Maximum number of
connections opened per host. Default is
1000.</span></p></td></tr></tbody></table></div><p>Settings related to
<strong>HTTP/2</strong> support (Apache CXF versions
<strong>4.0.2+</strong>/<strong>3.6.1+</strong>/<strong>3.5.7</strong>+/<strong>3.4.11+</strong>):</p><div
class="table-wrap"><table class="wrapped confluenceTable"><colgroup
span="1"><col span="1"><col span="1"><col span="1"></colgroup><tbody><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transports.http2.enabled</p></td><td
colspan="1" rowsp
an="1" class="confluenceTd"><p>true | false</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Allows HTTP/2 protocol if supported by the
server. Default is
<strong>false</strong>.</p></td></tr></tbody></table></div><p>Settings related
to Apache HttpAsyncClient threads and selectors:</p><div
class="table-wrap"><table class="wrapped confluenceTable"><colgroup
span="1"><col span="1"><col span="1"></colgroup><tbody><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.ioThreadCount</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Number of threads
HttpAsyncClient uses to process IO events. Default is "-1" which means one
thread per CPU core.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.interestOpQueued
<strong>(*)</strong></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>true/false for whether the interest ops are queues or
process directly.</p></td></tr><tr>
<td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.selectInterval</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Default 1000 ms. How often the
selector thread wakes up if there are no events to process additional things
like queue expirations.</p></td></tr></tbody></table></div><p><strong>*
</strong>- for Apache HttpComponents 4.x only</p><p>Setting to control
which conduit is used</p><div class="table-wrap"><table class="wrapped
confluenceTable"><colgroup span="1"><col span="1"><col span="1"><col
span="1"></colgroup><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.transport.http.async.usePolicy</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>ALWAYS, ASYNC_ONLY,
NEVER.</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Similar in
meaning to the "use.async.http.conduit" context property described above.
Whether to use the HttpAsyncClient: ALWAYS for both synchronous and asynchron
ous calls, ASYNC_ONLY (default) for asynchronous calls only, NEVER will use
HTTPURLConnection for both types of
calls.</p></td></tr></tbody></table></div></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/cxf/content/docs/jax-rs-multiparts.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-multiparts.html (original)
+++ websites/production/cxf/content/docs/jax-rs-multiparts.html Thu May 11
01:42:50 2023
@@ -111,16 +111,16 @@ Apache CXF -- JAX-RS Multiparts
<div id="ConfluenceContent"><p><br clear="none"><span
style="font-size:2em;font-weight:bold">JAX-RS : Support for Multiparts</span>
- </p><p><br clear="none"></p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1683654228665 {padding: 0px;}
-div.rbtoc1683654228665 ul {margin-left: 0px;}
-div.rbtoc1683654228665 li {margin-left: 0px;padding-left: 0px;}
+<br clear="none"></p><p><br clear="none"></p><p><style
type="text/css">/*<![CDATA[*/
+div.rbtoc1683769366095 {padding: 0px;}
+div.rbtoc1683769366095 ul {margin-left: 0px;}
+div.rbtoc1683769366095 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1683654228665">
+/*]]>*/</style></p><div class="toc-macro rbtoc1683769366095">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSMultiparts-Readingattachments">Reading attachments</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSMultiparts-MultipartannotationandOptionalattachments">Multipart
annotation and Optional attachments</a></li></ul>
</li><li><a shape="rect" href="#JAXRSMultiparts-Writingattachments">Writing
attachments</a></li><li><a shape="rect"
href="#JAXRSMultiparts-UploadingfileswithClientAPI">Uploading files with Client
API</a></li><li><a shape="rect"
href="#JAXRSMultiparts-Readinglargeattachments">Reading large attachments</a>
-<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSMultiparts-Formsandmultiparts">Forms and multiparts</a></li><li><a
shape="rect"
href="#JAXRSMultiparts-Content-DispositionUTF-8filenames">Content-Disposition
UTF-8 file names</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSMultiparts-Formsandmultiparts">Forms and multiparts</a></li><li><a
shape="rect"
href="#JAXRSMultiparts-Content-DispositionUTF-8filenames">Content-Disposition
UTF-8 file names</a></li><li><a shape="rect"
href="#JAXRSMultiparts-Content-Type">Content-Type</a></li></ul>
</li><li><a shape="rect" href="#JAXRSMultiparts-XOPsupport">XOP
support</a></li><li><a shape="rect"
href="#JAXRSMultiparts-MultipartFilters">Multipart Filters</a></li><li><a
shape="rect" href="#JAXRSMultiparts-SigningMultiparts">Signing
Multiparts</a></li><li><a shape="rect"
href="#JAXRSMultiparts-NoteaboutStruts">Note about Struts</a></li></ul>
</div><h1 id="JAXRSMultiparts-Readingattachments">Reading
attachments</h1><p>Individual parts can be mapped to StreamSource, InputStream,
DataSource or custom Java types for which message body readers are
available.</p><p>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">@POST
@@ -182,7 +182,7 @@ public Response addBookJaxbJson(
@Multipart("rootPart") Book2 b1,
@Multipart("book2") Book b2) {}
</pre>
-</div></div><p>the runtime will return a 400 status if either "rootPart" or
"book2" parts can not be found in the multipart payload.<br clear="none">
Starting from 2.5.1 it is possible to request the runtime to report a null
value in case of missing parts:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>the runtime will return a 400 status if either "rootPart" or
"book2" parts can not be found in the multipart payload.<br
clear="none">Starting from 2.5.1 it is possible to request the runtime to
report a null value in case of missing parts:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">@POST
@Path("/books/jaxbjson")
@Produces("text/xml")
@@ -278,7 +278,7 @@ client.post(getClass().getResource("imag
</jaxrs:server>
</beans>
</pre>
-</div></div><p>Note that such properties can be set up on a per-endpoint
basis. Alternatively you can set "attachmentDirectory", "attachmentThreshold"
and "attachmentMaxSize" properties directly on either
org.apache.cxf.jaxrs.provider.MultipartProvider or, when dealing with
multipart/form-data payloads,
org.apache.cxf.jaxrs.provider.FormEncodingProvider.</p><p>Alternatively, you
might want to set the following system properties which will apply to all
endpoints:</p><p>> -Dorg.apache.cxf.io.CachedOutputStream.Threshold=102400
<br clear="none"> and<br clear="none"> >
-Dorg.apache.cxf.io.CachedOutputStream.OutputDirectory=/temp</p><p>Starting
from CXF 2.5.0 and 2.4.4:<br clear="none"> >
-Dorg.apache.cxf.io.CachedOutputStream.MaxSize=10000000</p><p>Note that if a
given attachment exceeds the maximum size property (default is no-limit) then
HTTP 413 status will be returned. For more information on these configuration
properties, please see the documentation on <a shape="rect" hr
ef="securing-cxf-services.html">Securing CXF Services</a>.</p><h2
id="JAXRSMultiparts-Formsandmultiparts">Forms and multiparts</h2><p>The <a
shape="rect" class="external-link"
href="http://www.w3.org/TR/html401/interact/forms.html"; rel="nofollow">Forms in
HTML documents</a> recommendation <a shape="rect" class="external-link"
href="http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2";
rel="nofollow">suggests</a> that multipart/form-data requests should mainly be
used to upload files.</p><p>As mentioned in the previous section, one way to
deal with multipart/form-data submissions is to deal directly with a CXF JAXRS
Attachment class and get a Content-Disposition header and/or the underlying
input stream.</p><p>It is now possible (since 2.2.5) to have individual
multipart/form-data parts read by registered JAX-RS MessageBodyReaders,
something that is already possible to do for types like multipart/mixed or
multipart/related.</p><p>For example this <a shape="rect" class="extern
al-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/resources/attachmentFormJson";>request</a>
can be handled by a method with the following signature:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note that such properties can be set up on a per-endpoint
basis. Alternatively you can set "attachmentDirectory", "attachmentThreshold"
and "attachmentMaxSize" properties directly on either
org.apache.cxf.jaxrs.provider.MultipartProvider or, when dealing with
multipart/form-data payloads,
org.apache.cxf.jaxrs.provider.FormEncodingProvider.</p><p>Alternatively, you
might want to set the following system properties which will apply to all
endpoints:</p><p>> -Dorg.apache.cxf.io.CachedOutputStream.Threshold=102400
<br clear="none">and<br clear="none">>
-Dorg.apache.cxf.io.CachedOutputStream.OutputDirectory=/temp</p><p>Starting
from CXF 2.5.0 and 2.4.4:<br clear="none">>
-Dorg.apache.cxf.io.CachedOutputStream.MaxSize=10000000</p><p>Note that if a
given attachment exceeds the maximum size property (default is no-limit) then
HTTP 413 status will be returned. For more information on these configuration
properties, please see the documentation on <a shape="rect" href=
"securing-cxf-services.html">Securing CXF Services</a>.</p><h2
id="JAXRSMultiparts-Formsandmultiparts">Forms and multiparts</h2><p>The <a
shape="rect" class="external-link"
href="http://www.w3.org/TR/html401/interact/forms.html"; rel="nofollow">Forms in
HTML documents</a> recommendation <a shape="rect" class="external-link"
href="http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2";
rel="nofollow">suggests</a> that multipart/form-data requests should mainly be
used to upload files.</p><p>As mentioned in the previous section, one way to
deal with multipart/form-data submissions is to deal directly with a CXF JAXRS
Attachment class and get a Content-Disposition header and/or the underlying
input stream.</p><p>It is now possible (since 2.2.5) to have individual
multipart/form-data parts read by registered JAX-RS MessageBodyReaders,
something that is already possible to do for types like multipart/mixed or
multipart/related.</p><p>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/resources/attachmentFormJson";>request</a>
can be handled by a method with the following signature:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">@POST
@Path("/books/jsonform")
@Consumes("multipart/form-data")
@@ -299,7 +299,7 @@ public Response addBookJaxbJsonForm(@Mul
public Response addBookFilesForm(@Multipart("owner") String name,
@Multipart("files") List<Book> books)
{}
</pre>
-</div></div><p>If you need to know the names of the individual file parts
embedded in a "files" outer part (such as "book1" and "book2"), then please use
List<Attachment> instead. It is currently not possible to use a Multipart
annotation to refer to such inner parts but you can easily get the names from
the individual Attachment instances representing these inner parts.</p><p>Note
that it is only the last request which has been structured according to the
recommendation on how to upload multiple files but it is more complex than the
other simpler requests linked to in this section.</p><p>Please note that using
JAX-RS FormParams is recommended for dealing with plain
application/www-url-encoded submissions consisting of name/value pairs
only.</p><h2
id="JAXRSMultiparts-Content-DispositionUTF-8filenames">Content-Disposition
UTF-8 file names</h2><p>Starting from CXF 3.0.4 it is possible to specify a
Content-Disposition file names in a UTF-8 format, using a "filename*"
Content-Dis
position extension parameter as opposed to the "filename" one.</p><p>Please
see <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc6266"; rel="nofollow">RFC 6266</a> and <a
shape="rect" class="external-link"
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob;f=core/src/test/java/org/apache/cxf/attachment/AttachmentUtilTest.java;h=6eeedd42e965f4df8390ee6077222b34e1520732;hb=HEAD";>this
unit test</a> for more information. </p><h1
id="JAXRSMultiparts-XOPsupport">XOP support</h1><p>CXF JAXRS clients and
endpoints can support <a shape="rect" class="external-link"
href="http://www.w3.org/TR/xop10/"; rel="nofollow">XML-binary Optimized
Packaging (XOP)</a>.<br clear="none"> What it means at a practical level is
that a JAXB bean containing binary data is serialized using a multipart
packaging, with the root part containing non-binary data only but also linking
to co-located parts containing the actual binary payloads. Next it is
deserialized into a JAXB
bean on the server side.</p><p>If you'd like to experiment with XOP then you
need to set an "mtom-enabled" property on CXF jaxrs endpoints and clients.<br
clear="none"> Please see <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/JAXRSMultipartTest.java";>JAXRSMultipartTest</a>
(testXopWebClient) and <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/MultipartStore.java";>MultipartStore</a>
(addBookXop) for more details.</p><h1
id="JAXRSMultiparts-MultipartFilters">Multipart Filters</h1><p> </p><p>It
is possible to intercept the attachment write or read process starting from CXF
3.1.12.</p><p><a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartInputFilter.java";
rel="nofollow">MultipartInp
utFilter</a> and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartOutputFilter.java";
rel="nofollow">MultipartOutputFilter</a> have been introduced. These filters
can be used to modify the list of the attachment parts or customize some of the
individual part's properties, example, replace the part input stream,
etc.</p><p>These filters can be registered from JAX-RS 2.0 client or container
request/response filters or CXF in/out interceptors. <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartInputFilter.java";
rel="nofollow">MultipartInputFilter</a> <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/utils/multipart/AttachmentUtils.java#L71";
rel="nofollow">can be added</a> to the
list of the input filters which is identified by a "multipart.input.filters"
property on the current CXF message. Likewise, <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartOutputFilter.java";
rel="nofollow">MultipartOutputFilter</a> <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/utils/multipart/AttachmentUtils.java#L61";
rel="nofollow">can be added</a> to the list of the output filters which is
identified by a "multipart.output.filters" property on the current CXF
message.</p><h1 id="JAXRSMultiparts-SigningMultiparts">Signing
Multiparts</h1><p>See <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-jose.html#JAX-RSJOSE-SigningandVerificationofHTTPAttachments";>this
section</a> for more information.</p><h1
id="JAXRSMultiparts-NoteaboutStruts">Note about Struts</h1><p>If you a
re using CXF and <a shape="rect" class="external-link"
href="http://struts.apache.org/2.2.1/index.html";>Struts2</a> within the same
application and expecting CXF to process multipart/form-data payloads then you
need to make sure Struts2 dispatcher is not consuming the request input
stream.</p><p>One option is to let Struts2 handle URIs matching some specific
patterns only, for example:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p>If you need to know the names of the individual file parts
embedded in a "files" outer part (such as "book1" and "book2"), then please use
List<Attachment> instead. It is currently not possible to use a Multipart
annotation to refer to such inner parts but you can easily get the names from
the individual Attachment instances representing these inner parts.</p><p>Note
that it is only the last request which has been structured according to the
recommendation on how to upload multiple files but it is more complex than the
other simpler requests linked to in this section.</p><p>Please note that using
JAX-RS FormParams is recommended for dealing with plain
application/www-url-encoded submissions consisting of name/value pairs
only.</p><h2
id="JAXRSMultiparts-Content-DispositionUTF-8filenames">Content-Disposition
UTF-8 file names</h2><p>Starting from CXF 3.0.4 it is possible to specify a
Content-Disposition file names in a UTF-8 format, using a "filename*"
Content-Dis
position extension parameter as opposed to the "filename" one.</p><p>Please
see <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc6266"; rel="nofollow">RFC 6266</a> and <a
shape="rect" class="external-link"
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob;f=core/src/test/java/org/apache/cxf/attachment/AttachmentUtilTest.java;h=6eeedd42e965f4df8390ee6077222b34e1520732;hb=HEAD";>this
unit test</a> for more information. </p><h2
id="JAXRSMultiparts-Content-Type">Content-Type</h2><p>If the content type
(<strong>Content-Type</strong>) of the attachment is not set, it is assumed to
be "application/octet-stream". This default could be overridden.</p><div
class="table-wrap"><table class="confluenceTable"><colgroup span="1"><col
span="1"><col span="1"></colgroup><tbody><tr><th colspan="1" rowspan="1"
scope="col" class="confluenceTh">Property</th><th colspan="1" rowspan="1"
scope="col" class="confluenceTh"><br clear="none"></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd">org.apache.cxf.attachment.content-type</td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The default value for AttachmentDataSource
content type in case when "Content-Type" header is not
present.</p></td></tr></tbody></table></div><h1
id="JAXRSMultiparts-XOPsupport">XOP support</h1><p>CXF JAXRS clients and
endpoints can support <a shape="rect" class="external-link"
href="http://www.w3.org/TR/xop10/"; rel="nofollow">XML-binary Optimized
Packaging (XOP)</a>.<br clear="none">What it means at a practical level is that
a JAXB bean containing binary data is serialized using a multipart packaging,
with the root part containing non-binary data only but also linking to
co-located parts containing the actual binary payloads. Next it is deserialized
into a JAXB bean on the server side.</p><p>If you'd like to experiment with XOP
then you need to set an "mtom-enabled" property on CXF jaxrs endpoints and
clients.<br clear="none">Please see <a shape="rec
t" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/JAXRSMultipartTest.java";>JAXRSMultipartTest</a>
(testXopWebClient) and <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/MultipartStore.java";>MultipartStore</a>
(addBookXop) for more details.</p><h1
id="JAXRSMultiparts-MultipartFilters">Multipart Filters</h1><p><br
clear="none"></p><p>It is possible to intercept the attachment write or read
process starting from CXF 3.1.12.</p><p><a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartInputFilter.java";
rel="nofollow">MultipartInputFilter</a> and <a shape="rect"
class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartOut
putFilter.java" rel="nofollow">MultipartOutputFilter</a> have been introduced.
These filters can be used to modify the list of the attachment parts or
customize some of the individual part's properties, example, replace the part
input stream, etc.</p><p>These filters can be registered from JAX-RS 2.0 client
or container request/response filters or CXF in/out interceptors. <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartInputFilter.java";
rel="nofollow">MultipartInputFilter</a> <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/utils/multipart/AttachmentUtils.java#L71";
rel="nofollow">can be added</a> to the list of the input filters which is
identified by a "multipart.input.filters" property on the current CXF message.
Likewise, <a shape="rect" class="external-link" href="https://g
ithub.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartOutputFilter.java"
rel="nofollow">MultipartOutputFilter</a> <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/utils/multipart/AttachmentUtils.java#L61";
rel="nofollow">can be added</a> to the list of the output filters which is
identified by a "multipart.output.filters" property on the current CXF
message.</p><h1 id="JAXRSMultiparts-SigningMultiparts">Signing
Multiparts</h1><p>See <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-jose.html#JAX-RSJOSE-SigningandVerificationofHTTPAttachments";>this
section</a> for more information.</p><h1
id="JAXRSMultiparts-NoteaboutStruts">Note about Struts</h1><p>If you are using
CXF and <a shape="rect" class="external-link"
href="http://struts.apache.org/2.2.1/index.html";>Struts2</a> within the same
application and expecting CXF to process multipart
/form-data payloads then you need to make sure Struts2 dispatcher is not
consuming the request input stream.</p><p>One option is to let Struts2 handle
URIs matching some specific patterns only, 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"><web-app>
<filter>
<filter-name>struts2</filter-name>
