JAX-RS Integration with MIME MultiPart Message Formats
The classes in this package provide for integration of
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:
- Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies (RFC 2045)
- Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types (RFC 2046)
- Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text (RFC 2047)
- Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures (RFC 2048)
- Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples (RFC 2049)
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:
MIME-Version: 1.0HTTP header is included on generated responses. It is accepted, but not required, on processed requests.
MessageBodyReaderimplementation for consuming MIME MultiPart entities. See below for usage restrictions.
MessageBodyWriterimplementation for producing MIME MultiPart entities. The appropriate
Provideris used to serialize each body part, based on its media type.
- Optional creation of an appropriate
boundaryparameter on a generated
Content-Typeheader, if not already present.
- Top level content type of
multipart, with the following supported subtypes:
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
BodyPart, and then call the
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:
charsetparameter on the
Content-Typeheader field. Currently, the hard coded charset is FIXME. [RFC2045#5.2]
Content-Transfer-Encodingheader field. [RFC2045#6]
message/*family of content types.
ClassDescriptionA mutable model representing a body part nested inside a MIME MultiPart entity.Utility for creating boundary parameters.A content disposition header.ContentDisposition.ContentDispositionBuilder<T extends ContentDisposition.ContentDispositionBuilder,
V extends ContentDisposition>Builder to build content disposition.Subclass of
BodyPartwith specialized support for media type
multipart/form-data.A form-data content disposition header.Builder to build form data content disposition.Subclass of
MultiPartwith specialized support for media type
multipart/form-data.Binds the named body part(s) of a "multipart/form-data" request entity body to a resource method parameter.A parameter-based exception for errors with
FormDataParam.Jersey implementation of
EntityPart.Builder.A mutable model representing a MIME MultiPart entity.Feature used to register Multipart providers.Automatic registration of
MediaType(and associated String) manifest constants.Injectable JavaBean containing the configuration parameters for
jersey-multipartas used in this particular application.