org.glassfish.jersey.media.multipart.package-info Maven / Gradle / Ivy
Show all versions of jersey-all Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2010-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
/**
* 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.
*
*/
package org.glassfish.jersey.media.multipart;