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>
You can implement the IBM JAX-RS to receive
the data in parts, so you can process these parts yourself, if needed.
Procedure
- Create a resource method. You 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 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.
- Optional: For JAX-RS 1.1, 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 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 yourself.