Author: buildbot
Date: Mon May 15 13:47:41 2017
New Revision: 1012260
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
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/jax-rs-multiparts.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-multiparts.html (original)
+++ websites/production/cxf/content/docs/jax-rs-multiparts.html Mon May 15
13:47:41 2017
@@ -121,16 +121,16 @@ Apache CXF -- JAX-RS Multiparts
 </p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1494589627980 {padding: 0px;}
-div.rbtoc1494589627980 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1494589627980 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1494856023801 {padding: 0px;}
+div.rbtoc1494856023801 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1494856023801 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1494589627980">
+/*]]>*/</style></p><div class="toc-macro rbtoc1494856023801">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSMultiparts-Readingattachments">Reading attachments</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSMultiparts-MultipartannotationandOptionalattachments">Multipart
annotation and Optional attachments</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSMultiparts-Writingattachments">Writing
attachments</a></li><li><a shape="rect"
href="#JAX-RSMultiparts-UploadingfileswithClientAPI">Uploading files with
Client API</a></li><li><a shape="rect"
href="#JAX-RSMultiparts-Readinglargeattachments">Reading large attachments</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSMultiparts-Formsandmultiparts">Forms and multiparts</a></li><li><a
shape="rect"
href="#JAX-RSMultiparts-Content-DispositionUTF-8filenames">Content-Disposition
UTF-8 file names</a></li></ul>
-</li><li><a shape="rect" href="#JAX-RSMultiparts-XOPsupport">XOP
support</a></li><li><a shape="rect"
href="#JAX-RSMultiparts-MultipartFilters">Multipart Filters</a></li><li><a
shape="rect" href="#JAX-RSMultiparts-NoteaboutStruts">Note about
Struts</a></li></ul>
+</li><li><a shape="rect" href="#JAX-RSMultiparts-XOPsupport">XOP
support</a></li><li><a shape="rect"
href="#JAX-RSMultiparts-MultipartFilters">Multipart Filters</a></li><li><a
shape="rect" href="#JAX-RSMultiparts-SigningMultiparts">Signing
Multiparts</a></li><li><a shape="rect"
href="#JAX-RSMultiparts-NoteaboutStruts">Note about Struts</a></li></ul>
</div><h1 id="JAX-RSMultiparts-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"
style="font-size:12px;">@POST
@Path("/books/jaxbjson")
@@ -308,7 +308,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="JAX-RSMultiparts-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-Di
sposition 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="JAX-RSMultiparts-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 JAX
B 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="JAX-RSMultiparts-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">Multipart
InputFilter</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 t
he 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><p> </p><h1 id="JAX-RSMultiparts-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">
+</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="JAX-RSMultiparts-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-Di
sposition 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="JAX-RSMultiparts-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 JAX
B 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="JAX-RSMultiparts-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">Multipart
InputFilter</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 t
he 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="JAX-RSMultiparts-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="JAX-RSMultiparts-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: xml; gutter: false; theme: Default"
style="font-size:12px;"><web-app>
<filter>
<filter-name>struts2</filter-name>
