JAX-RS Integration with MIME MultiPart Message Formats

The classes in this package provide for integration of multipart/* request and response bodies in a JAX-RS runtime environment. The set of registered providers is leveraged, in that the content type for a body part of such a message reuses the same MessageBodyReader/MessageBodyWriter implementations as would be used for that content type as a standalone entity.

For more information on the syntax and semantics of MIME multipart streams, see the following RFCs:

Implementation Notes

The following notes describe significant aspects of the implementation of the MIME MultiPart APIs in this (and related) packages:

  • Although packaged as a Jersey extension, the runtime code in this library should be portable to any compliant JAX-RS implementation. Jersey is only required for execution of the unit tests.

Supported MIME Multipart Capabilities

The following list of general MIME MultiPart features is currently supported:

  • The MIME-Version: 1.0 HTTP header is included on generated responses. It is accepted, but not required, on processed requests.
  • A MessageBodyReader implementation for consuming MIME MultiPart entities. See below for usage restrictions.
  • A MessageBodyWriter implementation for producing MIME MultiPart entities. The appropriate Provider is used to serialize each body part, based on its media type.
  • Optional creation of an appropriate boundary parameter on a generated Content-Type header, if not already present.
  • Top level content type of multipart, with the following supported subtypes: alternative, digest, mixed, and parallel.

At present, the MessageBodyReader implementation exhibits a usability issue. It is not currently possible to know ahead of time what Java class the application would prefer to use for each individual body part, so an appropriate Provider cannot be selected. Currently, the unparsed content of each body part is returned (as a byte array) in the entity property of the returned BodyPart} instance, and the application can decide what further steps are needed based on the headers included in that body part. The simplest technique is to examine the received BodyPart, and then call the getEntityAs() method once you know which implementation class you would prefer.

Not (Yet) Supported MIME Multipart Capabilities

The following list of general MIME MultiPart features is NOT (yet, in most cases) supported:

  • The charset parameter on the Content-Type header field. Currently, the hard coded charset is FIXME. [RFC2045#5.2]
  • The Content-Transfer-Encoding header field. [RFC2045#6]
  • The message/* family of content types.