Package org.glassfish.jersey.media.multipart

package org.glassfish.jersey.media.multipart

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:

• 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)

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.

Related Packages

Package	Description
org.glassfish.jersey.media.multipart.file	Provides support for body parts that are file attachments.

Class	Description
BodyPart	A mutable model representing a body part nested inside a MIME MultiPart entity.
BodyPartEntity	Proxy class representing the entity of a BodyPart when a MultiPart entity is received and parsed.
Boundary	Utility for creating boundary parameters.
ContentDisposition	A content disposition header.
ContentDisposition.ContentDispositionBuilder<T extends ContentDisposition.ContentDispositionBuilder,V extends ContentDisposition>	Builder to build content disposition.
FormDataBodyPart	Subclass of BodyPart with specialized support for media type multipart/form-data.
FormDataContentDisposition	A form-data content disposition header.
FormDataContentDisposition.FormDataContentDispositionBuilder	Builder to build form data content disposition.
FormDataMultiPart	Subclass of MultiPart with specialized support for media type multipart/form-data.
FormDataParam	Binds the named body part(s) of a "multipart/form-data" request entity body to a resource method parameter.
FormDataParamException	A parameter-based exception for errors with FormDataParam.
JerseyEntityPartBuilderProvider	Jersey implementation of EntityPart.Builder.
MultiPart	A mutable model representing a MIME MultiPart entity.
MultiPartFeature	Feature used to register Multipart providers.
MultiPartFeatureAutodiscoverable	Automatic registration of MultiPartFeature.
MultiPartMediaTypes	Convenience MediaType (and associated String) manifest constants.
MultiPartProperties	Injectable JavaBean containing the configuration parameters for jersey-multipart as used in this particular application.