## Package com.sun.jersey.multipart

JAX-RS Integration with MIME MultiPart Message Formats

See:
Description

Class Summary
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.
FormDataBodyPart | Subclass of `BodyPart` with specialized support for media type `multipart/form-data`.
FormDataMultiPart | Subclass of `MultiPart` with specialized support for media type `multipart/form-data`.
MultiPart | A mutable model representing a MIME MultiPart entity.
MultiPartConfig | Injectable JavaBean containing the configuration parameters for `jersey-multipart` as used in this particular application.
MultiPartMediaTypes | Convenience `MediaType` (and associated String) manifest constants.

Annotation Types Summary
FormDataParam | Binds the named body part(s) of a "multipart/form-data" request entity body to a resource method parameter.

## Package com.sun.jersey.multipart Description

### 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.

Copyright © 2017 Oracle Corporation. All Rights Reserved.