When writing a JAX-RS service, RESTEasy provides an interface that allows you to read in any multipart mime type:

package org.jboss.resteasy.plugins.providers.multipart;

import java.util.List;

public interface MultipartInput {

   List<InputPart> getParts();

   String getPreamble();

   /**
    * Call this method to delete any temporary files created from unmarshalling this multipart message
    * Otherwise they will be deleted on Garbage Collection or JVM exit.
    */
   void close();
}

MultipartInput is a simple interface that allows you to get access to each part of the multipart message. Each part is represented by an InputPart interface:

package org.jboss.resteasy.plugins.providers.multipart;

import javax.ws.rs.core.GenericType;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import java.io.IOException;
import java.lang.reflect.Type;

/**
 * Represents one part of a multipart message.
 */
public interface InputPart {
   /**
    * If no content-type header is sent in a multipart message part
    * "text/plain; charset=ISO-8859-1" is assumed.
    * <p>
    * This can be overwritten by setting a different String value in
    * {@link org.jboss.resteasy.spi.HttpRequest#setAttribute(String, Object)}
    * with this ("resteasy.provider.multipart.inputpart.defaultContentType")
    * String as key. It should be done in a
    * {@link javax.ws.rs.container.ContainerRequestFilter}.
    * </p>
    */
   String DEFAULT_CONTENT_TYPE_PROPERTY = "resteasy.provider.multipart.inputpart.defaultContentType";

   /**
    * If there is a content-type header without a charset parameter, charset=US-ASCII
    * is assumed.
    * <p>
    * This can be overwritten by setting a different String value in
    * {@link org.jboss.resteasy.spi.HttpRequest#setAttribute(String, Object)}
    * with this ("resteasy.provider.multipart.inputpart.defaultCharset")
    * String as key. It should be done in a
    * {@link javax.ws.rs.container.ContainerRequestFilter}.
    * </p>
    */
   String DEFAULT_CHARSET_PROPERTY = "resteasy.provider.multipart.inputpart.defaultCharset";

   /**
    * @return headers of this part
    */
   MultivaluedMap<String, String> getHeaders();

   String getBodyAsString() throws IOException;

   <T> T getBody(Class<T> type, Type genericType) throws IOException;

   <T> T getBody(GenericType<T> type) throws IOException;

   /**
    * @return "Content-Type" of this part
    */
   MediaType getMediaType();

   /**
    * @return true if the Content-Type was resolved from the message, false if
    *         it was resolved from the server default
    */
   boolean isContentTypeFromMessage();

   /**
    * Change the media type of the body part before you extract it.  Useful for specifying a charset.
    *
    * @param mediaType media type
    */
   void setMediaType(MediaType mediaType);
}}

Each part has a set of headers associated with it. You can unmarshall the part by calling one of the getBody() methods. The Type genericType parameter can be null, but the Class type parameter must be set. RESTEasy will find a MessageBodyReader based on the media type of the part as well as the type information you pass in. The following piece of code is unmarshalling parts which are XML into a JAXB annotated class called Customer:

@Path("/multipart")
public class MyService
{
    @PUT
    @Consumes("multipart/mixed")
    public void put(MultipartInput input)
    {
        List<Customer> customers = new ArrayList...;
        for (InputPart part : input.getParts())
        {
            Customer cust = part.getBody(Customer.class, null);
            customers.add(cust);
        }
        input.close();
    }
}

Sometimes you may want to unmarshall a body part that is sensitive to generic type metadata. In this case you can use the org.jboss.resteasy.util.GenericType class. Here's an example of unmarshalling a type that is sensitive to generic type metadata:

@Path("/multipart")
public class MyService
{
    @PUT
    @Consumes("multipart/mixed")
    public void put(MultipartInput input)
    {
        for (InputPart part : input.getParts())
        {
            List<Customer> cust = part.getBody(new GenericType<List<Customer>>() {});
        }
        input.close();
    }
}

Use of GenericType is required because it is really the only way to obtain generic type information at runtime.

If your body parts are uniform, you do not have to manually unmarshall each and every part. You can just provide a java.util.List as your input parameter. It must have the type it is unmarshalling with the generic parameter of the List type declaration. Here's an example again of unmarshalling a list of customers:

@Path("/multipart")
public class MyService
{
    @PUT
    @Consumes("multipart/mixed")
    public void put(List<Customer> customers)
    {
        ...
    }
}

When writing a JAX-RS service, RESTEasy provides an interface that allows you to read in multipart/form-data mime type. "multipart/form-data" is often found in web application HTML Form documents and is generally used to upload files. The form-data format is the same as other multipart formats, except that each inlined piece of content has a name associated with it. The interface used for form-data input is MultipartFormDataInput

package org.jboss.resteasy.plugins.providers.multipart;

import java.io.IOException;
import java.lang.reflect.Type;
import java.util.List;
import java.util.Map;

import javax.ws.rs.core.GenericType;

public interface MultipartFormDataInput extends MultipartInput {
   /**
    * @return A parameter map containing a list of values per name.
    */
   Map<String, List<InputPart>> getFormDataMap();

   <T> T getFormDataPart(String key, Class<T> rawType, Type genericType)
         throws IOException;

   <T> T getFormDataPart(String key, GenericType<T> type) throws IOException;
}

It works in much the same way as MultipartInput described earlier in this chapter.

With form-data, if your body parts are uniform, you do not have to manually unmarshall each and every part. You can just provide a java.util.Map as your input parameter. It must have the type it is unmarshalling with the generic parameter of the List type declaration. Here's an example of of unmarshalling a Map of Customer objects which are JAXB annotated classes.

@Path("/multipart")
public class MyService
{
    @PUT
    @Consumes("multipart/form-data")
    public void put(Map<String, Customer> customers)
    {
        ...
    }
}

When writing a JAX-RS service, RESTEasy provides an interface that allows you to read in multipart/related mime type. A multipart/related is used to indicate that message parts should not be considered individually but rather as parts of an aggregate whole. One example usage for multipart/related is to send a web page complete with images in a single message. Every multipart/related message has a root/start part that references the other parts of the message. The parts are identified by their "Content-ID" headers. multipart/related is defined by RFC 2387. The interface used for related input is MultipartRelatedInput

package org.jboss.resteasy.plugins.providers.multipart;

import java.util.Map;

/**
 * Represents a multipart/related (RFC2387) incoming mime message. A
 * multipart/related message is used to hold a root or start part and other
 * parts which are referenced from the root part. All parts have a unique id.
 * The type and the id of the start part is presented in parameters in the
 * message content-type header.
 */
public interface MultipartRelatedInput extends MultipartInput {

   /**
    * The type parameter as it was read from the content-type header of the
    * multipart/related message. A well formed multipart/related message always
    * has this parameter. This is the type of the root part of the message. If
    * a content-type header is presented in the root part as well it should
    * hold the same value.
    *
    * @return the type parameter of the content-type header of the message,
    *         null if there was no such parameter
    */
   String getType();

   /**
    * A start parameter is not mandatory in a message. If it is presented it
    * holds the id of the root part.
    *
    * @return the start parameter of the content-type header of the message,
    *         null if there was no such parameter
    */
   String getStart();

   /**
    * Optional.
    *
    * @return the start-info parameter of the content-type header of the
    *         message, null if there was no such parameter
    */
   String getStartInfo();

   /**
    * @return the root part of the message. If a start parameter was set in the
    *         message header the part with that id is returned. If no start
    *         parameter was set the first part is returned.
    */
   InputPart getRootPart();

   /**
    * @return a map holding all parts with their unique id-s as keys. The root
    *         part and the related parts too.
    */
   Map<String, InputPart> getRelatedMap();
}

It works in much the same way as MultipartInput described earlier in this chapter.

RESTEasy provides a simple API to output multipart data:

public class MultipartOutput
{
   public OutputPart addPart(Object entity, MediaType mediaType);

   public OutputPart addPart(Object entity, MediaType mediaType, String filename);

   public OutputPart addPart(Object entity, MediaType mediaType, String filename, boolean utf8Encode);

   public OutputPart addPart(Object entity, GenericType<?> type, MediaType mediaType);

   public OutputPart addPart(Object entity, GenericType<?> type, MediaType mediaType, String filename);

   public OutputPart addPart(Object entity, GenericType<?> type, MediaType mediaType, String filename, boolean utf8Encode);

   public OutputPart addPart(Object entity, Class<?> type, Type genericType, MediaType mediaType);

   public OutputPart addPart(Object entity, Class<?> type, Type genericType, MediaType mediaType, String filename);

   public OutputPart addPart(Object entity, Class<?> type, Type genericType, MediaType mediaType, String filename, boolean utf8Encode);

   public List<OutputPart> getParts();

   public String getBoundary();

   public void setBoundary(String boundary);
}

public class OutputPart {
   public OutputPart(final Object entity, final Class<?> type, final Type genericType, final MediaType mediaType);

   public OutputPart(final Object entity, final Class<?> type, final Type genericType, final MediaType mediaType, final String filename);

   public OutputPart(final Object entity, final Class<?> type, final Type genericType, final MediaType mediaType, final String filename, final boolean utf8Encode);

   public MultivaluedMap<String, Object> getHeaders();

   public Object getEntity();

   public Class<?> getType();

   public Type getGenericType();

   public MediaType getMediaType();

   public String getFilename();

   public boolean isUtf8Encode();
}

From the above definitions we can see that the output part can accept parameter called utf8Encode, and if you set this to true then the underlying AbstractMultipartFormDataWriter will process the filename according to rfc5987:

private String getFilename(OutputPart part) {
  String filename = part.getFilename();
  if (filename == null) {
     return "";
  } else {
     if (part.isUtf8Encode()) {
        String encodedFilename = filename;
        try {
           encodedFilename = URLEncoder.encode(filename, "UTF-8");
           // append encoding charset into the value if and only if encoding was needed
           if (!encodedFilename.equals(filename)) {
           // encoding was needed, so per rfc5987 we have to prepend charset
              return "; filename*=utf-8''" + encodedFilename.replaceAll("\\+", "%20");
           }
        } catch (UnsupportedEncodingException e) {
           // should not happen
        }
     }
     return "; filename=\"" + filename + "\"";
  }
}

When you want to output multipart data it is as simple as creating a MultipartOutput object and calling addPart() methods. RESTEasy will automatically find a MessageBodyWriter to marshall your entity objects. Like MultipartInput, sometimes you may have marshalling which is sensitive to generic type metadata. In that case, use GenericType. Most of the time though passing in an Object and its MediaType is enough. In the example below, we are sending back a "multipart/mixed" format back to the calling client. The parts are Customer objects which are JAXB annotated and will be marshalling into "application/xml".

@Path("/multipart")
public class MyService
{
    @GET
    @Produces("multipart/mixed")
    public MultipartOutput get()
    {
        MultipartOutput output = new MultipartOutput();
        output.addPart(new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
        output.addPart(new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
        return output;
    }
}

If your body parts are uniform, you do not have to manually marshall each and every part or even use a MultipartOutput object. You can just provide a java.util.List. It must have the generic type it is marshalling with the generic parameter of the List type declaration. You must also annotate the method with the @PartType annotation to specify what media type each part is. Here's an example of sending back a list of customers back to a client(the customers are JAXB objects):

@Path("/multipart")
public class MyService
{
    @GET
    @Produces("multipart/mixed")
    @PartType("application/xml")
    public List<Customer> get()
    {
        ...
    }
}

RESTEasy provides a simple API to output multipart/form-data:

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartFormDataOutput extends MultipartOutput
{
    public OutputPart addFormData(String key, Object entity, MediaType mediaType)

    public OutputPart addFormData(String key, Object entity, GenericType type, MediaType mediaType)

    public OutputPart addFormData(String key, Object entity, Class type, Type genericType, MediaType mediaType)

    public Map<String, OutputPart> getFormData()

    public Map<String, List<OutputPart>> getFormDataMap()
}

When you want to output multipart/form-data it is as simple as creating a MultipartFormDataOutput object and calling addFormData() methods. RESTEasy will automatically find a MessageBodyWriter to marshall your entity objects. Like MultipartInput, sometimes you may have marshalling which is sensitive to generic type metadata. In that case, use GenericType. Most of the time though passing in an Object and its MediaType is enough. In the example below, we are sending back a "multipart/form-data" format back to the calling client. The parts are Customer objects which are JAXB annotated and will be marshalling into "application/xml".

@Path("/form")
public class MyService
{
    @GET
    @Produces("multipart/form-data")
    public MultipartFormDataOutput get()
    {
        MultipartFormDataOutput output = new MultipartFormDataOutput();
        output.addPart("bill", new Customer("bill"), MediaType.APPLICATION_XML_TYPE);
        output.addPart("monica", new Customer("monica"), MediaType.APPLICATION_XML_TYPE);
        return output;
    }
}

When using form-data format the named content can be a list of OutputPart objects as long as each object in the named list contains a uniform object and media type. In the example below, we are sending back a "multipart/form-data" format which consists of two named list of objects, bill and monica:

@Path("/form")
public class MyService {
   @GET
   @Produces("multipart/form-data")
   public MultipartFormDataOutput get() {
      MultipartFormDataOutput output = new MultipartFormDataOutput();
      output.addPart("smith", new Customer("Joe Smith"), MediaType.APPLICATION_XML_TYPE);
      output.addPart("monica", new Employee("monica"), MediaType.APPLICATION_JSON_TYPE);
      output.addPart("smith", new Customer("Deb Smith"), MediaType.APPLICATION_XML_TYPE);
      output.addPart("smith", new Customer("Buba Smith"), MediaType.APPLICATION_XML_TYPE);
      return output;
   }
}

If your body parts are uniform, you do not have to manually marshall each and every part or even use a MultipartFormDataOutput object. You can just provide a java.util.Map. It must have the generic type it is marshalling with the generic parameter of the Map type declaration. You must also annotate the method with the @PartType annotation to specify what media type each part is. Here's an example of sending back a list of customers back to a client(the customers are JAXB objects):

@Path("/multipart")
public class MyService
{
    @GET
    @Produces("multipart/form-data")
    @PartType("application/xml")
    public Map<String, Customer> get()
    {
        ...
    }
}

RESTEasy provides a simple API to output multipart/related.

package org.jboss.resteasy.plugins.providers.multipart;

public class MultipartRelatedOutput extends MultipartOutput {
    public OutputPart getRootPart()

    public OutputPart addPart(Object entity, MediaType mediaType,
        String contentId, String contentTransferEncoding)

    public String getStartInfo()

    public void setStartInfo(String startInfo)
}

When you want to output multipart/related it is as simple as creating a MultipartRelatedOutput object and calling addPart() methods. The first added part will be used as the root part of the multipart/related message. RESTEasy will automatically find a MessageBodyWriter to marshall your entity objects. Like MultipartInput, sometimes you may have marshalling which is sensitive to generic type metadata. In that case, use GenericType. Most of the time though passing in an Object and its MediaType is enough. In the example below, we are sending back a "multipart/related" format back to the calling client. We are sending a html with 2 images.

@Path("/related")
public class MyService
{
    @GET
    @Produces("multipart/related")
    public MultipartRelatedOutput get()
    {
        MultipartRelatedOutput output = new MultipartRelatedOutput();
        output.setStartInfo("text/html");

        Map<String, String> mediaTypeParameters = new LinkedHashMap<String, String>();
        mediaTypeParameters.put("charset", "UTF-8");
        mediaTypeParameters.put("type", "text/html");
        output.addPart(
            "<html><body>\n"
            + "This is me: <img src='cid:http://example.org/me.png' />\n"
            + "<br />This is you: <img src='cid:http://example.org/you.png' />\n"
            + "</body></html>",
            new MediaType("text", "html", mediaTypeParameters),
            "<mymessage.xml@example.org>", "8bit");
        output.addPart("// binary octets for me png",
            new MediaType("image", "png"), "<http://example.org/me.png>",
            "binary");
        output.addPart("// binary octets for you png", new MediaType(
            "image", "png"),
            "<http://example.org/you.png>", "binary");
        client.putRelated(output);
        return output;
    }
}

If you have a exact knowledge of your multipart/form-data packets, you can map them to and from a POJO class to and from multipart/form-data using the @org.jboss.resteasy.annotations.providers.multipart.MultipartForm annotation and the JAX-RS @FormParam annotation. You simple define a POJO with at least a default constructor and annotate its fields and/or properties with @FormParams. These @FormParams must also be annotated with @org.jboss.resteasy.annotations.providers.multipart.PartType if you are doing output. For example:

public class CustomerProblemForm {
    @FormParam("customer")
    @PartType("application/xml")
    private Customer customer;

    @FormParam("problem")
    @PartType("text/plain")
    private String problem;

    public Customer getCustomer() { return customer; }
    public void setCustomer(Customer cust) { this.customer = cust; }
    public String getProblem() { return problem; }
    public void setProblem(String problem) { this.problem = problem; }
}

After defining your POJO class you can then use it to represent multipart/form-data. Here's an example of sending a CustomerProblemForm using the RESTEasy client framework:

@Path("portal")
public interface CustomerPortal {

   @Path("issues/{id}")
   @Consumes("multipart/form-data")
   @PUT
   public void putProblem(@MultipartForm CustomerProblemForm,
                          @PathParam("id") int id) {
      CustomerPortal portal = ProxyFactory.create(CustomerPortal.class, "http://example.com");
      CustomerProblemForm form = new CustomerProblemForm();
      form.setCustomer(...);
      form.setProblem(...);

      portal.putProblem(form, 333);
   }
}

You see that the @MultipartForm annotation was used to tell RESTEasy that the object has @FormParam and that it should be marshalled from that. You can also use the same object to receive multipart data. Here is an example of the server side counterpart of our customer portal.

@Path("portal")
public class CustomerPortalServer {

    @Path("issues/{id})
    @Consumes("multipart/form-data")
    @PUT
    public void putIssue(@MultipartForm CustoemrProblemForm,
                         @PathParam("id") int id) {
       ... write to database...
    }
}

In addition to the XML data format, you can also use JSON formatted data to represent your POJO classes. To achieve this goal, you need to plug in a JSON provider into your project. For example, you can add RESTEasy Jackson2 Provider into your project's dependency scope:

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-jackson2-provider</artifactId>
    <version>${resteasy.ver}</version>
</dependency>

And then you can write an ordinary POJO class, which Jackson2 can automatically serialize/deserialize it in JSON format:

public class JsonUser {
   private String name;

   public JsonUser() {
   }

   public JsonUser(final String name) {
      this.name = name;
   }

   public String getName() {
      return name;
   }

   public void setName(String name) {
      this.name = name;
   }
}

The resource class can be written like this:

import org.jboss.resteasy.annotations.providers.multipart.MultipartForm;
import org.jboss.resteasy.annotations.providers.multipart.PartType;

import javax.ws.rs.Consumes;
import javax.ws.rs.FormParam;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;

@Path("/")
public class JsonFormResource {

    public JsonFormResource() {
    }

    public static class Form {

    @FormParam("user")
    @PartType("application/json")
    private JsonUser user;

    public Form() {
    }

    public Form(final JsonUser user) {
    this.user = user;
    }

    public JsonUser getUser() {
      return user;
    }
    }

    @PUT
    @Path("form/class")
    @Consumes("multipart/form-data")
    public String putMultipartForm(@MultipartForm Form form) {
         return form.getUser().getName();
    }
}

As the code shown above, you can see the PartType of JsonUser is marked as "application/json", and it's included in the "@MultipartForm Form" class instance.

To send request to the resource method, you need to send JSON formatted data that is corresponding with the JsonUser class. The easiest to do this is to use a proxy class that has the same definition like the resource class. Here is the sample code of the proxy class that is corresponding with the JsonFormResource class:

import org.jboss.resteasy.annotations.providers.multipart.MultipartForm;

import javax.ws.rs.Consumes;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;

@Path("/")
public interface JsonForm {

@PUT
@Path("form/class")
@Consumes("multipart/form-data")
  String putMultipartForm(@MultipartForm JsonFormResource.Form form);
}

And then you can use the proxy class above to send request to the resource method correctly. Here is the sample code:

ResteasyClient client = (ResteasyClient)ClientBuilder.newClient();
...
JsonForm proxy = client.target("your_request_url_address").proxy(JsonForm.class);
String name = proxy.putMultipartForm(new JsonFormResource.Form(new JsonUser("bill")));
...

And if your client side has Jackson2 provider included, your request will be marshaled correctly, and your JsonUser data will be converted into JSON format and then send to the server side. You can also use hand-crafted JSON data as your request and send it to server side, but you have to make sure the request data is in correct form then.

There are a lot of frameworks doing multipart parsing automatically with the help of filters and interceptors. Like org.jboss.seam.web.MultipartFilter in Seam or org.springframework.web.multipart.MultipartResolver in Spring. However the incoming multipart request stream can be parsed only once. RESTEasy users working with multipart should make sure that nothing parses the stream before RESTEasy gets it.

By default if no Content-Type header is present in a part, "text/plain; charset=us-ascii" is used as fallback. This is the value defined by the MIME RFC. However for example some web clients (like most, if not all, web browsers) do not send Content-Type headers for all fields in a multipart/form-data request (only for the file parts). This can cause character encoding and unmarshalling errors on the server side. To correct this there is an option to define an other, non-rfc compliant fallback value. This can be done dynamically per request with the PreProcessInterceptor infrastructure of RESTEasy. In the following example we will set "*/*; charset=UTF-8" as the new default fallback:

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements PreProcessInterceptor {

    public ServerResponse preProcess(HttpRequest request, ResourceMethod method)
            throws Failure, WebApplicationException {
        request.setAttribute(InputPart.DEFAULT_CONTENT_TYPE_PROPERTY, "*/*; charset=UTF-8");
        return null;
    }
}

Using an interceptor and the InputPart.DEFAULT_CONTENT_TYPE_PROPERTY attribute allows setting a default Content-Type, but it is also possible to override the Content-Type, if any, in any input part by calling org.jboss.resteasy.plugins.providers.multipart.InputPart.setMediaType(). For example:

@POST
@Path("query")
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Produces(MediaType.TEXT_PLAIN)
public Response setMediaType(MultipartInput input) throws IOException
{
    List<InputPart> parts = input.getParts();
    InputPart part = parts.get(0);
    part.setMediaType(MediaType.valueOf("application/foo+xml"));
    String s = part.getBody(String.class, null);
    ...
}

Sometimes, a part may have a Content-Type header with no charset parameter. If the InputPart.DEFAULT_CONTENT_TYPE_PROPERTY property is set and the value has a charset parameter, that value will be appended to an existing Content-Type header that has no charset parameter. It is also possible to specify a default charset using the constant InputPart.DEFAULT_CHARSET_PROPERTY (actual value "resteasy.provider.multipart.inputpart.defaultCharset"):

import org.jboss.resteasy.plugins.providers.multipart.InputPart;

@Provider
@ServerInterceptor
public class ContentTypeSetterPreProcessorInterceptor implements PreProcessInterceptor {

    public ServerResponse preProcess(HttpRequest request, ResourceMethod method)
            throws Failure, WebApplicationException {
        request.setAttribute(InputPart.DEFAULT_CHARSET_PROPERTY, "UTF-8");
        return null;
    }
}

If both InputPart.DEFAULT_CONTENT_TYPE_PROPERTY and InputPart.DEFAULT_CHARSET_PROPERTY are set, then the value of InputPart.DEFAULT_CHARSET_PROPERTY will override any charset in the value of InputPart.DEFAULT_CONTENT_TYPE_PROPERTY.