<chapter id="Multipart">
    <title>Multipart Providers</title>
    <para>RESTEasy has rich support for the "multipart/*" and "multipart/form-data" mime types. The multipart mime
        format is used to pass lists of content bodies. Multiple content bodies are embedded in one message.
        "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.
    </para>
    <para>RESTEasy provides
        a custom API for reading and writing multipart types as well as marshalling arbitrary List (for any multipart
        type)
        and Map (multipart/form-data only)
        objects
    </para>
    <section id="MultipartInput">
        <title>Input with multipart/mixed</title>
        <para>When writing a JAX-RS service, RESTEasy provides an interface that allows you to read in any
            multipart mime type:
        </para>
        <programlisting><![CDATA[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();
}]]></programlisting>

        <para>
            <code>MultipartInput</code>
            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:
        </para>

        <programlisting><![CDATA[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);
}}]]></programlisting>
        <para>
            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:
        </para>
        <programlisting><![CDATA[@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();
    }
}]]></programlisting>
        <para>
            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:
        </para>
        <programlisting><![CDATA[@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();
    }
}]]></programlisting>
        <para>
            Use of GenericType is required because it is really the only way to obtain generic type information at
            runtime.
        </para>
    </section>
    <section id="multipart_list">
        <title>java.util.List with multipart data</title>
        <para>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:
        </para>
        <programlisting><![CDATA[
@Path("/multipart")
public class MyService
{
    @PUT
    @Consumes("multipart/mixed")
    public void put(List<Customer> customers)
    {
        ...
    }
}]]></programlisting>
        The above example will accept the multipart data of a list of customers, and unmarshall them correctly.
    </section>
    <section id="MultipartFormData">
        <title>Input with multipart/form-data</title>
        <para>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
            <code>MultipartFormDataInput</code>
        </para>
        <programlisting><![CDATA[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;
}]]></programlisting>
        <para>
            It works in much the same way as MultipartInput described earlier in this chapter.
        </para>

    </section>
    <section id="multipart_map">
        <title>java.util.Map with multipart/form-data</title>
        <para>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.
        </para>
        <programlisting><![CDATA[@Path("/multipart")
public class MyService
{
    @PUT
    @Consumes("multipart/form-data")
    public void put(Map<String, Customer> customers)
    {
        ...
    }
}]]></programlisting>
    </section>
    <section id="MultipartRelated">
        <title>Input with multipart/related</title>
        <para>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
            <code>MultipartRelatedInput</code>
        </para>
        <programlisting><![CDATA[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();
}]]></programlisting>
        <para>
            It works in much the same way as MultipartInput described earlier in this chapter.
        </para>

    </section>
    <section id="multipart_output">
        <title>Output with multipart</title>
        <para>RESTEasy provides a simple API to output multipart data:</para>
        <programlisting><![CDATA[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);
}]]></programlisting>

        Each part is represented by an <code>OutputPart</code> interface:
        <programlisting><![CDATA[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();
}]]></programlisting>

        <para>From the above definitions we can see that the output part can accept parameter called <code>utf8Encode</code>, and if you set this to <code>true</code> then the underlying <code>AbstractMultipartFormDataWriter</code> will process the filename according to rfc5987:</para>
        <programlisting><![CDATA[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 + "\"";
  }
}]]></programlisting>
        <para>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".
        </para>
        <programlisting><![CDATA[@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;
    }
}]]></programlisting>
    </section>
    <section id="multipart_list_output">
        <title>Multipart Output with java.util.List</title>
        <para>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):
        </para>
        <programlisting><![CDATA[@Path("/multipart")
public class MyService
{
    @GET
    @Produces("multipart/mixed")
    @PartType("application/xml")
    public List<Customer> get()
    {
        ...
    }
}]]></programlisting>
    </section>
    <section id="multipart_formdata_output">
        <title>Output with multipart/form-data</title>
        <para>RESTEasy provides a simple API to output multipart/form-data:</para>
        <programlisting><![CDATA[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()
}
]]></programlisting>
        <para>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".
        </para>
        <programlisting><![CDATA[@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;
    }
}]]></programlisting>
        <para>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:
        </para>
        <programlisting><![CDATA[@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;
   }
}]]></programlisting>
    </section>
    <section id="multipart_map_output">
        <title>Multipart FormData Output with java.util.Map</title>
        <para>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):
        </para>
        <programlisting><![CDATA[@Path("/multipart")
public class MyService
{
    @GET
    @Produces("multipart/form-data")
    @PartType("application/xml")
    public Map<String, Customer> get()
    {
        ...
    }
}]]></programlisting>
    </section>
    <section id="multipart_related_output">
        <title>Output with multipart/related</title>
        <para>RESTEasy provides a simple API to output multipart/related.</para>
        <programlisting><![CDATA[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)
}]]></programlisting>
        <para>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.
        </para>
        <programlisting><![CDATA[@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;
    }
}]]></programlisting>
    </section>
    <section id="multipartform_annotation">
        <title>@MultipartForm and POJOs</title>
        <para>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:
        </para>
        <programlisting><![CDATA[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; }
}]]></programlisting>
        <para>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:
        </para>
        <programlisting><![CDATA[@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);
   }
}]]></programlisting>
        <para>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.
        </para>
        <programlisting><![CDATA[@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...
    }
}]]></programlisting>
        <para>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:
        </para>
        <programlisting><![CDATA[<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-jackson2-provider</artifactId>
    <version>${resteasy.ver}</version>
</dependency>
]]></programlisting>
        <para>
            And then you can write an ordinary POJO class, which Jackson2 can automatically serialize/deserialize it in
            JSON format:
        </para>
        <programlisting><![CDATA[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;
   }
}]]></programlisting>
        <para>The resource class can be written like this:</para>
        <programlisting><![CDATA[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();
    }
}]]></programlisting>
        <para>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.
        </para>
        <para>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:
        </para>
        <programlisting><![CDATA[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);
}]]></programlisting>
       <para>And then you can use the proxy class above to send request to the resource method correctly.
           Here is the sample code:</para>
<programlisting><![CDATA[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")));
...]]></programlisting>
        <para>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.
        </para>
    </section>
    <section id="xop_with_multipart_related">
        <title>XML-binary Optimized Packaging (Xop)</title>
        <para>RESTEasy supports Xop messages packaged as multipart/related. What does this mean? If you have a JAXB
            annotated POJO that also holds some binary content you may choose to send it in such a way where the binary
            does not need to be encoded in any way (neither base64 neither hex). This results in faster transport while
            still using the convenient POJO. More about Xop can be read here:
            <link linkend="http://www.w3.org/TR/xop10/">http://www.w3.org/TR/xop10/</link>. Now lets see an example:
        </para>
        <para>First we have a JAXB annotated POJO to work with. @XmlMimeType tells JAXB the mime type of the binary
            content (its not required to do XOP packaging but it is recommended to be set if you know the exact type):
        </para>
        <programlisting><![CDATA[@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public static class Xop {

    private Customer bill;
    private Customer monica;

    @XmlMimeType(MediaType.APPLICATION_OCTET_STREAM)
    private byte[] myBinary;

    @XmlMimeType(MediaType.APPLICATION_OCTET_STREAM)
    private DataHandler myDataHandler;

    // methods, other fields ...
}]]></programlisting>
        <para>In the above POJO myBinary and myDataHandler will be processed as binary attachments while the whole Xop
            object will be sent as xml (in the places of the binaries only their references will be generated).
            javax.activation.DataHandler is the most general supported type so if you need an java.io.InputStream or a
            javax.activation.DataSource you need to go with the DataHandler. Some other special types are supported too:
            java.awt.Image and javax.xml.transform.Source. Let's assume that Customer is also JAXB friendly POJO in the
            above example (of course it can also have binary parts). Now lets see a an example Java client that sends
            this:
        </para>
        <programlisting><![CDATA[// our client interface:
@Path("mime")
public static interface MultipartClient {
    @Path("xop")
    @PUT
    @Consumes(MultipartConstants.MULTIPART_RELATED)
    public void putXop(@XopWithMultipartRelated Xop bean);
}

// Somewhere using it:
{
    MultipartClient client = ProxyFactory.create(MultipartClient.class,
        "http://www.example.org");
    Xop xop = new Xop(new Customer("bill"), new Customer("monica"),
        "Hello Xop World!".getBytes("UTF-8"),
        new DataHandler(new ByteArrayDataSource("Hello Xop World!".getBytes("UTF-8"),
        MediaType.APPLICATION_OCTET_STREAM)));
    client.putXop(xop);
}]]></programlisting>
	<para>We used @Consumes(MultipartConstants.MULTIPART_RELATED) to tell RESTEasy that we want to send multipart/related
	packages (that's the container format that will hold our Xop message). We used @XopWithMultipartRelated to tell
	RESTEasy that we want to make Xop messages. So we have a POJO and a client service that is willing to send it. All
	we need now a server that can read it:</para>
<programlisting><![CDATA[@Path("/mime")
public class XopService {
    @PUT
    @Path("xop")
    @Consumes(MultipartConstants.MULTIPART_RELATED)
    public void putXopWithMultipartRelated(@XopWithMultipartRelated Xop xop) {
        // do very important things here
    }
}]]></programlisting>
        <para>We used @Consumes(MultipartConstants.MULTIPART_RELATED) to tell RESTEasy that we want to read
            multipart/related
            packages. We used @XopWithMultipartRelated to tell RESTEasy that we want to read Xop messages. Of course we
            could
            also produce Xop return values but we would than also need to annotate that and use a Produce annotation,
            too.
        </para>
    </section>
    <section id="multipart_parsing_note">
        <title>Note about multipart parsing and working with other frameworks</title>
        <para>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.
        </para>
    </section>
    <section id="multipart_overwrite_default_content_type">
        <title>Overwriting the default fallback content type for multipart messages</title>
        <para>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:
            <programlisting><![CDATA[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;
    }
}]]></programlisting>
        </para>
    </section>

    <section id="multipart_overwrite_content_type">
        <title>Overwriting the content type for multipart messages</title>
        <para>Using an interceptor and the
            <code>InputPart.DEFAULT_CONTENT_TYPE_PROPERTY</code>
            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
            <methodname>org.jboss.resteasy.plugins.providers.multipart.InputPart.setMediaType()</methodname>.
            For example:
        </para>

        <programlisting><![CDATA[@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);
    ...
}]]></programlisting>

    </section>

    <section id="multipart_overwrite_default_charset">
        <title>Overwriting the default fallback charset for multipart messages</title>

        <para>Sometimes, a part may have a Content-Type header with no charset parameter. If the
            <code>InputPart.DEFAULT_CONTENT_TYPE_PROPERTY</code>
            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
            <code>InputPart.DEFAULT_CHARSET_PROPERTY</code>
            (actual value "resteasy.provider.multipart.inputpart.defaultCharset"):
        </para>

        <programlisting><![CDATA[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;
    }
}]]></programlisting>

        <para>If both <code>InputPart.DEFAULT_CONTENT_TYPE_PROPERTY</code> and
            <code>InputPart.DEFAULT_CHARSET_PROPERTY</code>
            are set, then the value of
            <code>InputPart.DEFAULT_CHARSET_PROPERTY</code>
            will override any charset in the value of
            <code>InputPart.DEFAULT_CONTENT_TYPE_PROPERTY</code>.
        </para>
    </section>
</chapter>
