JAX-RS : Support for Multiparts

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")
@Produces("text/xml")
public Response addBookJaxbJson(
        @Multipart(value = "rootPart", type = "text/xml") Book2 b1,
        @Multipart(value = "book2", type = "application/json") Book b2) 
        throws Exception {
}

Note that in this example it's expected that the root part named 'rootPart' is a text-xml Book representation, while a part named 'book2' is a Book JSON sequence.

All attachment parts can be accessed as a list of Attachment with Attachment making it easy to deal with a given part:

@POST
public void addAttachments(List<Attachment> atts) throws Exception {
}

For example, Attachment class can be used to get to a Content-Disposition header, when dealing with the form submission of files.

Similarly, the whole request body can be represented as a MultipartBody:

@POST
public void addAttachments(MultipartBody body) throws Exception {
body.getAllAtachments();
body.getRootAttachment();
}

When handling complex multipart/form-data submissions (such as those containing files) MultipartBody (and Attachment) need to be used directly. In simpler cases, when every form part can be captured by a String, the following code will suffice:

@POST
@Consumes("multipart/form-data")
public void addForm1(@FormParam("name") String title, @FormParam("id") Long id) throws Exception {
}

@POST
@Consumes("multipart/form-data")
public void addForm2(@FormParam("") BookBean book) throws Exception {
}

@POST
@Consumes("multipart/form-data")
public void addForm3(MultivaluedMap<String, String> formData) throws Exception {
}

When working with either List of Attachments or MultipartBody, one may want to process the individual parts with the help of some custom procedures. Starting from CXF 2.3.0 it is also possible to do the following:

@POST
public void addAttachments(MultipartBody body) throws Exception {
    Book book = body.getAttachmentObject("bookPart", Book.class);
}

@POST
public void addAttachments(List<Attachment> attachments) throws Exception {
    for (Attachment attachment : attachments) {
        Book book = attachment.getObject(Book.class);
    }  
}

When a user code has MessageContext injected, AttachmentUtils can also be used by the application code.

Please see these test resource class and blog entry for more examples.

Multipart annotation and Optional attachments

When you write the code like this

@POST
@Path("/books/jaxbjson")
@Produces("text/xml")
public Response addBookJaxbJson(
        @Multipart("rootPart") Book2 b1,
        @Multipart("book2") Book b2)  {}

the runtime will return a 400 status if either "rootPart" or "book2" parts can not be found in the multipart payload.
Starting from 2.5.1 it is possible to request the runtime to report a null value in case of missing parts:

@POST
@Path("/books/jaxbjson")
@Produces("text/xml")
public Response addBookJaxbJson(
        @Multipart("rootPart") Book2 b1,
        @Multipart(value = "book2", required = false) Book b2) {}

The above code requires the "rootPart" part be available and can handle the case where the "book2" part is missing.

Writing attachments

Starting from 2.2.4 it is also possible to write attachments to the output stream, both on the client and server sides.

On the server side it is sufficient to update the @Produces value for a given method:

public class Resource {
   private List<Book> books; 
   @Produces("multipart/mixed;type=text/xml")
   public List<Book> getBooksAsMultipart() {
      return booksList;
   }

   @Produces("multipart/mixed;type=text/xml")
   public Book getBookAsMultipart() {
      return booksList;
   }
}

Note that a 'type' parameter of the 'multipart/mixed' media type indicates that all parts in the multiparts response should have a Content-Type header set to 'text/xml' for both getBooksAsMultipart() and getBookAsMultipart() method responses. The getBooksAsMultipart() response will have 3 parts, the first part will have its Content-ID header set to "root.message@cxf.apache.org", the next parts will have '1' and '2' ids. The getBookAsMultipart() response will have a single part only with its Content-ID header set to "root.message@cxf.apache.org".

When returning mixed multiparts containing objects of different types, you can either return a Map with the media type string value to Object pairs or MultipartBody:

public class Resource {
   private List<Book> books; 
   @Produces("multipart/mixed")
   public Map<String, Object> getBooks() {
      Map<String, Object> map = new LinkedHashMap<String, Object>();
      map.put("text/xml", new JaxbBook());
      map.put("application/json", new JSONBook());
      map.put("application/octet-stream", imageInputStream);
      return map;  
   } 

   @Produces("multipart/mixed")
   public MultipartBody getBooks2() {
      List<Attachment> atts = new LinkedList<Attachment>();
      atts.add(new Attachment("root", "application/json", new JSONBook()));
      atts.add(new Attachment("image", "application/octet-stream", getImageInputStream()));
      return new MultipartBody(atts, true);  
   }

}

Similarly to the method returning a list in a previous code fragment, getBooks() will have the response serialized as multiparts, where the first part will have its Content-ID header set to "root.message@cxf.apache.org", the next parts will have ids like '1', '2', etc.

In getBooks2() one can control the content ids of individual parts.

You can also control the contentId and the media type of the root attachment by using a Multipart annotation:

public class Resource {
   @Produces("multipart/form-data")
   @Multipart(value = "root", type = "application/octet-stream") 
   public File testGetImageFromForm() {
      return getClass().getResource("image.png").getFile();
   }
}

One can also have lists or maps of DataHandler, DataSource, Attachment, byte arrays or InputStreams handled as multiparts.

On the client side multiparts can be written the same way. For example:

WebClient client = WebClient.create("http://books");
client.type("multipart/mixed").accept("multipart/mixed");
List<Attachment> atts = new LinkedList<Attachment>();
atts.add(new Attachment("root", "application/json", new JSONBook()));
atts.add(new Attachment("image", "application/octet-stream", getImageInputStream()));
List<Attachment> atts = client.postAndGetCollection(atts, Attachment.class);

Note a new WebClient.postAndGetCollection which can be used for a type-safe retrieval of collections. A similar WebClient.getCollection has also been added.

When using proxies, a Multipart annotation attached to a method parameter can also be used to set the root contentId and media type. Proxies do not support at the moment multiple method parameters annotated with Multipart (as opposed to the server side) but only a single multipart parameter:

public class Resource {
    @Produces("multipart/mixed")
    @Consumes("multipart/form-data")
    @Multipart(value = "root", type = "application/octet-stream") 
    public File postGetFile(@Multipart(value = "root2", type = "application/octet-stream") File file) {}
}

A method-level Multipart annotation will affect the writing on the server side and the reading on the client side. A parameter-level Multipart annotation will affect writing on the client (proxy) side and reading on the server side. You don't have to use Multipart annotations.

Uploading files with Client API

At the moment the only way to upload a file is to use a MultipartBody, Attachment or File:

WebClient client = WebClient.create("http://books");
client.type("multipart/form-data");
ContentDisposition cd = new ContentDisposition("attachment;filename=image.jpg");
Attachment att = new Attachment("root", imageInputStream, cd);
client.post(new MultipartBody(att));

// or just post the attachment if it's a single part request only
client.post(att);

// or just use a file
client.post(getClass().getResource("image.png").getFile());

Using File provides a simpler way as the runtime can figure out how to create a ContentDisposition from a File.

Reading large attachments

One can use the following properties to set up folder, memory threshold and max size (from CXF 2.4.4 and 2.5) values when dealing with large attachments:

<beans>
  <jaxrs:server id="bookstore1">
     <jaxrs:properties>
         <entry key="attachment-directory" value="/temp/bookstore1"/>
         <!-- 200K-->
         <entry key="attachment-memory-threshold" value="404800"/>
         
         <entry key="attachment-max-size" value="404800"/>
     </jaxrs:properties>
  </jaxrs:server>  
</beans>

Note that such properties can be set up on a per-endpoint basis. Alternatively you can set "attachmentDirectory", "attachmentThreshold" and "attachmentMaxSize" properties directly on either org.apache.cxf.jaxrs.provider.MultipartProvider or, when dealing with multipart/form-data payloads, org.apache.cxf.jaxrs.provider.FormEncodingProvider.

Alternatively, you might want to set the following system properties which will apply to all endpoints:

> -Dorg.apache.cxf.io.CachedOutputStream.Threshold=102400
and
> -Dorg.apache.cxf.io.CachedOutputStream.OutputDirectory=/temp

Starting from CXF 2.5.0 and 2.4.4:
> -Dorg.apache.cxf.io.CachedOutputStream.MaxSize=10000000

Note that if a given attachment exceeds the maximum size property (default is no-limit) then HTTP 413 status will be returned. For more information on these configuration properties, please see the documentation on Securing CXF Services.

Forms and multiparts

The Forms in HTML documents recommendation suggests that multipart/form-data requests should mainly be used to upload files.

As mentioned in the previous section, one way to deal with multipart/form-data submissions is to deal directly with a CXF JAXRS Attachment class and get a Content-Disposition header and/or the underlying input stream.

It is now possible (since 2.2.5) to have individual multipart/form-data parts read by registered JAX-RS MessageBodyReaders, something that is already possible to do for types like multipart/mixed or multipart/related.

For example this request can be handled by a method with the following signature:

@POST
@Path("/books/jsonform")
@Consumes("multipart/form-data")
public Response addBookJsonFromForm(Book b1)  {...}

Similarly, this request can be handled by a method with the following signature:

@POST
@Path("/books/jsonjaxbform")
@Consumes("multipart/form-data")
public Response addBookJaxbJsonForm(@Multipart("jsonPart") Book b1,
                                        @Multipart("jaxbPart") Book b2) {}

Note that once a request has more than two parts then one needs to start using @Multipart, the values can refer to either ContentId header or to ContentDisposition/name. Note that at the moment using @Multipart is preferred to using @FormParam unless a plain name/value submission is dealt with. The reason is that @Multipart can also specify an expected media type of the individual part and thus act similarly to a @Consume annotation.

When dealing with multiple parts one can avoid using @Multipart and just use List, ex, List\<Atachment\>, List\<Book\>, etc.

Finally, multipart/form-data requests with multiple files (file uploads) can be supported too. For example, this request can be handled by a method with the signature like :

@POST
@Path("/books/filesform")
@Produces("text/xml")
@Consumes("multipart/form-data")
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-Disposition extension parameter as opposed to the "filename" one.

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

Content-Type

If the content type (Content-Type) of the attachment is not set, it is assumed to be "application/octet-stream". This default could be overridden.

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 JAXB 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.

MultipartInputFilter and MultipartOutputFilter 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.

These filters can be registered from JAX-RS 2.0 client or container request/response filters or CXF in/out interceptors. 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.

Signing Multiparts

See this section for more information.

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>
      <filter-class>
           org.apache.struts2.dispatcher.FilterDispatcher
       </filter-class>
   </filter>

   <filter-mapping>
       <filter-name>struts2</filter-name>
       <url-pattern>*.action</url-pattern>
   </filter-mapping>

   <filter-mapping>
       <filter-name>struts2</filter-name>
       <url-pattern>*.jsp</url-pattern>
   </filter-mapping>
</web-app>

Alternatively,disabling a "struts.multipart.parser" property might help.