Configure a resource to receive multipart/form-data parts from an HTML form submission

HTML forms that transmit file data must be configured with the POST method and the "multipart/form-data" action. This data can be received in one of two ways by the JAX-RS resource method that accepts it with the IBM Java API for RESTful Web Services (JAX-RS) implementation.

This task provides instructions for configuring a JAX-RS method to consume and produce multipart/form-data. The following example illustrates an HTML form:

<form action="http://www.example.com/" method="POST" enctype="multipart/form-data">
    <input type="text" name="fileid" />
    <br />
    <input type="text" name="description" />
    <br />
    <input type="file" name="thefile" />
    <br />
    <input type="submit" name="submit" value="submit"/>
</form>

We can implement the IBM JAX-RS to receive the data in parts, so we can process these parts ourself, if needed.

Tasks

1. Create a resource method. We must declare the following resource method to receive and echo multipart/form-data content from an HTTP POST:

   package com.example.jaxrs;
   @POST
   @Consumes("multipart/form-data")
   @Produces("multipart/form-data")
   
   public Response postFormData(@FormParam("fileid") int theFileid,
                                @FormParam("description") String theDescription,
                                @FormParam("thefile") File theFile) {
       // echo what we got in the form
       BufferedOutMultiPart bomp = new BufferedOutMultiPart();
       OutPart op = new OutPart();
       op.setBody(theFile);
       op.setContentType(MediaType.TEXT_PLAIN);  // or other appropriate type, based on the file we received
       bomp.setLocationHeader("thefile");
       bomp.addPart(op);
       op = new OutPart();
       op.setBody(theDescription);
       op.setContentType(MediaType.TEXT_PLAIN);
       bomp.setLocationHeader("description");
       bomp.addPart(op);
       BufferedOutMultiPart bomp = new BufferedOutMultiPart();
       OutPart op = new OutPart();
       op.setBody(theFileid + "");  // just in case theFileid is uninitialized
       op.setContentType(MediaType.TEXT_PLAIN);
       bomp.setLocationHeader("fileid");
       bomp.addPart(op);
   
       return Response.ok(bomp, "multipart/form-data").build();
   }
   

   The originator of the form POST submission can generate a Content-Transfer-Encoding header for one or more parts of the multipart message. The IBM JAX-RS implementation attempts to auto-decode the payload of the part according to this header when the header is of base64 or quoted-printable encoding type.

2. Optional: For JAX-RS 1.1, if we do not want the IBM JAX-RS implementation to auto-decode the part payload, put the @Encoded annotation on the method parameter. The following example illustrates the use of the @Encoded annotation on the method parameter:

   package com.example.jaxrs;
   @POST
   @Consumes("multipart/form-data")
   @Produces("multipart/form-data")
   public Response postFormData(@FormParam("fileid") int theFileid,
                                @FormParam("description") String theDescription,
                                @Encoded @FormParam("thefile") File theFile) {
       // don't auto-decode the file part payload
       ...
   }
   

   To have complete control of the retrieval and decoding of all parts in a multipart/form-data message, we can receive the BufferedInMultiPart object itself:

   package com.example.jaxrs;
   import org.apache.wink.common.model.multipart.BufferedInMultiPart;
   import org.apache.wink.common.model.multipart.InPart;
   @POST
   @Consumes("multipart/form-data")
   @Produces("multipart/form-data")
   public Response postFormData(BufferedInMultiPart bimp) {
       List<InPart> parts = bimp.getParts();
       // iterate over the "parts" and process them however you like
   }
   

You will receive and echo data from an HTTP POST with multipart/form-data Content-Type, by allowing the IBM JAX-RS implementation to split and auto-decode the parts for you, and by receiving the still encoded parts to process ourself.

Use multipart/form-data content in JAX-RS application requests and responses