cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1012117 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-multiparts.html
Date Fri, 12 May 2017 10:47:38 GMT
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>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;<span
class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS : Support for Multiparts</span>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</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>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;<span
style="font-size:2em;font-weight:bold">JAX-RS : Support for Multiparts</span>
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1435780130071">
+
+&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</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&lt;Book&gt; 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&lt;Attachment&gt;
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.&#160;</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&lt;Attachment&gt;
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.&#160;</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>&#160;</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,&#160;<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>&#160;</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;">&lt;web-app&gt;
 &lt;filter&gt;
       &lt;filter-name&gt;struts2&lt;/filter-name&gt;



Mime
View raw message