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>