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

About this task

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>
The IBM JAX-RS implementation allows you to receive the data in parts, so you can process these parts yourself, if needed.

Procedure

  1. Create a resource method. For the resource method to receive and echo multipart/form-data content from an HTTP POST, you must declare it:
    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 you 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) If you 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
        ...
    }
    If you want to have complete control of the retrieval and decoding of all parts in a multipart/form-data message, you 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
    }

Results

You have received and echoed 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 yourself.

Task topic    

Terms and conditions for information centers | Feedback

Last updated: April 20, 2014 08:46 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_multipart_formdata_from_html
File name: twbs_jaxrs_multipart_formdata_from_html.html