Forms and multiparts - 7.3

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

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 also possible 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 payload:

--bqJky99mlBWa-ZuqjC53mG6EzbmlxB
Content-Disposition: form-data; name="bookJson"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Content-ID: <jsonPart>

{"Book":{"name":"CXF in Action - 1","id":123}}

--bqJky99mlBWa-ZuqjC53mG6EzbmlxB
Content-Disposition: form-data; name="bookXML"
Content-Type: application/xml
Content-Transfer-Encoding: 8bit
Content-ID: <jaxbPart>
<Book><name>CXF in Action</name></Book>
--bqJky99mlBWa-ZuqjC53mG6EzbmlxB--       

can be handled by the following method:

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

Note that once a request has more than two parts then one needs to start using @Mutipart, the values can refer to either ContentId header or to ContentDisposition/name. 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<Atachment>, List<Book>, etc.

Finally, multipart/form-data requests with multiple files (file uploads) can be supported. For example, this payload:

--bqJky99mlBWa-ZuqjC53mG6EzbmlxB
Content-Disposition: form-data; name="owner"
Content-Type: text/plain

Larry
--bqJky99mlBWa-ZuqjC53mG6EzbmlxB
Content-Disposition: form-data; name="files"
Content-Type: multipart/mixed; boundary=_Part_4_701508.1145579811786

--_Part_4_701508.1145579811786
Content-Disposition: form-data; name="book1"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit

{"Book":{"name":"CXF in Action - 1","id":123}}
--_Part_4_701508.1145579811786
Content-Disposition: form-data; name="book2"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit

{"Book":{"name":"CXF in Action - 2","id":124}}
--_Part_4_701508.1145579811786--
--bqJky99mlBWa-ZuqjC53mG6EzbmlxB--

can be handled by the following method:

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