Reading attachments

Individual parts can be mapped to StreamSource, InputStream, DataSource or custom Java types for which message body readers are available.

For example:

@POST
 @Path("/books/jaxbjson")
@@ -305,7 +308,7 @@ public Response addBookJaxbJsonForm(@Mul
 public Response addBookFilesForm(@Multipart("owner") String name,
                                  @Multipart("files") List<Book> books) {}

-

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.

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.

Please note that using JAX-RS FormParams is recommended for dealing with plain application/www-url-encoded submissions consisting of name/value pairs only.

Content-Disposition UTF-8 file names

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.

Please see RFC 6266 and this unit test for more information.

XOP support

CXF JAXRS clients and endpoints can support XML-binary Optimized Packaging (XOP).
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.

If you'd like to experiment with XOP then you need to set an "mtom-enabled" property on CXF jaxrs endpoints and clients.
Please see JAXRSMultipartTest (testXopWebClient) and MultipartStore (addBookXop) for more details.

Note about Struts

If you are using CXF and Struts2 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.

One option is to let Struts2 handle URIs matching some specific patterns only, for example:

+

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.

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.

Please note that using JAX-RS FormParams is recommended for dealing with plain application/www-url-encoded submissions consisting of name/value pairs only.

Content-Disposition UTF-8 file names

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.

Please see RFC 6266 and this unit test for more information.

XOP support

CXF JAXRS clients and endpoints can support XML-binary Optimized Packaging (XOP).
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.

If you'd like to experiment with XOP then you need to set an "mtom-enabled" property on CXF jaxrs endpoints and clients.
Please see JAXRSMultipartTest (testXopWebClient) and MultipartStore (addBookXop) for more details.

Multipart Filters

It is possible to intercept the attachment write or read process starting from CXF 3.1.12.

Multipart InputFilter and MultipartOutputFilter 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.

These filters can be registered from JAX-RS 2.0 client or container request/response filters. MultipartInputFilter 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, MultipartOutputFilter can be added to the list of the output filters which is identified by a "multipart.output.filters" property on the current CXF message.

Note about Struts

If you are using CXF and Struts2 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.

One option is to let Struts2 handle URIs matching some specific patterns only, for example:

<web-app>
 <filter>
       <filter-name>struts2</filter-name>