Author: buildbot
Date: Fri May 12 10:47:37 2017
New Revision: 1012117
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 Fri May 12
10:47:37 2017
@@ -117,17 +117,20 @@ Apache CXF -- JAX-RS Multiparts
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div
id="ConfluenceContent"><p> </p><p> </p><p> </p><p> </p><p> <span
class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS : Support
for
Multiparts</span> </p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1435780130071 {padding: 0px;}
-div.rbtoc1435780130071 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1435780130071 li {margin-left: 0px;padding-left: 0px;}
+<div
id="ConfluenceContent"><p> </p><p> </p><p> </p><p> </p><p> <span
style="font-size:2em;font-weight:bold">JAX-RS : Support for Multiparts</span>
-/*]]>*/</style></p><div class="toc-macro rbtoc1435780130071">
+
+ </p><p> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
+div.rbtoc1494586024366 {padding: 0px;}
+div.rbtoc1494586024366 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1494586024366 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1494586024366">
<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-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-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")
@@ -305,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-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 attachments 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. <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> can be added 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/front
end/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/multipart/MultipartOutputFilter.java"
rel="nofollow">MultipartOutputFilter</a> can be added 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">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><web-app>
<filter>
<filter-name>struts2</filter-name>
