org.jvnet.mimepull.MimeUtility Maven / Gradle / Ivy
Show all versions of jersey-all Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-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.
*/
package org.jvnet.mimepull;
import java.io.*;
/**
* This is a utility class that provides various MIME related
* functionality.
*
* There are a set of methods to encode and decode MIME headers as
* per RFC 2047. Note that, in general, these methods are
* not needed when using methods such as
* setSubject and setRecipients; JavaMail
* will automatically encode and decode data when using these "higher
* level" methods. The methods below are only needed when maniuplating
* raw MIME headers using setHeader and getHeader
* methods. A brief description on handling such headers is given below:
*
* RFC 822 mail headers must contain only US-ASCII
* characters. Headers that contain non US-ASCII characters must be
* encoded so that they contain only US-ASCII characters. Basically,
* this process involves using either BASE64 or QP to encode certain
* characters. RFC 2047 describes this in detail.
*
* In Java, Strings contain (16 bit) Unicode characters. ASCII is a
* subset of Unicode (and occupies the range 0 - 127). A String
* that contains only ASCII characters is already mail-safe. If the
* String contains non US-ASCII characters, it must be encoded. An
* additional complexity in this step is that since Unicode is not
* yet a widely used charset, one might want to first charset-encode
* the String into another charset and then do the transfer-encoding.
*
* Note that to get the actual bytes of a mail-safe String (say,
* for sending over SMTP), one must do
*
*
* byte[] bytes = string.getBytes("iso-8859-1");
*
*
*
* The setHeader and addHeader methods
* on MimeMessage and MimeBodyPart assume that the given header values
* are Unicode strings that contain only US-ASCII characters. Hence
* the callers of those methods must insure that the values they pass
* do not contain non US-ASCII characters. The methods in this class
* help do this.
*
* The getHeader family of methods on MimeMessage and
* MimeBodyPart return the raw header value. These might be encoded
* as per RFC 2047, and if so, must be decoded into Unicode Strings.
* The methods in this class help to do this.
*
* Several System properties control strict conformance to the MIME
* spec. Note that these are not session properties but must be set
* globally as System properties.
*
* The mail.mime.decodetext.strict property controls
* decoding of MIME encoded words. The MIME spec requires that encoded
* words start at the beginning of a whitespace separated word. Some
* mailers incorrectly include encoded words in the middle of a word.
* If the mail.mime.decodetext.strict System property is
* set to "false", an attempt will be made to decode these
* illegal encoded words. The default is true.
*
* The mail.mime.encodeeol.strict property controls the
* choice of Content-Transfer-Encoding for MIME parts that are not of
* type "text". Often such parts will contain textual data for which
* an encoding that allows normal end of line conventions is appropriate.
* In rare cases, such a part will appear to contain entirely textual
* data, but will require an encoding that preserves CR and LF characters
* without change. If the mail.mime.encodeeol.strict
* System property is set to "true", such an encoding will
* be used when necessary. The default is false.
*
* In addition, the mail.mime.charset System property can
* be used to specify the default MIME charset to use for encoded words
* and text parts that don't otherwise specify a charset. Normally, the
* default MIME charset is derived from the default Java charset, as
* specified in the file.encoding System property. Most
* applications will have no need to explicitly set the default MIME
* charset. In cases where the default MIME charset to be used for
* mail messages is different than the charset used for files stored on
* the system, this property should be set.
*
* The current implementation also supports the following System property.
*
* The mail.mime.ignoreunknownencoding property controls
* whether unknown values in the Content-Transfer-Encoding
* header, as passed to the decode method, cause an exception.
* If set to "true", unknown values are ignored and 8bit
* encoding is assumed. Otherwise, unknown values cause a MessagingException
* to be thrown.
*
* @author John Mani
* @author Bill Shannon
*/
/* FROM mail.jar */
final class MimeUtility {
// This class cannot be instantiated
private MimeUtility() { }
private static final boolean ignoreUnknownEncoding =
PropUtil.getBooleanSystemProperty(
"mail.mime.ignoreunknownencoding", false);
/**
* Decode the given input stream. The Input stream returned is
* the decoded input stream. All the encodings defined in RFC 2045
* are supported here. They include "base64", "quoted-printable",
* "7bit", "8bit", and "binary". In addition, "uuencode" is also
* supported.
*
* In the current implementation, if the
* mail.mime.ignoreunknownencoding system property is set to
* "true", unknown encoding values are ignored and the
* original InputStream is returned.
*
* @param is input stream
* @param encoding the encoding of the stream.
* @return decoded input stream.
* @exception MessagingException if the encoding is unknown
*/
public static InputStream decode(InputStream is, String encoding)
throws DecodingException {
if (encoding.equalsIgnoreCase("base64"))
return new BASE64DecoderStream(is);
else if (encoding.equalsIgnoreCase("quoted-printable"))
return new QPDecoderStream(is);
else if (encoding.equalsIgnoreCase("uuencode") ||
encoding.equalsIgnoreCase("x-uuencode") ||
encoding.equalsIgnoreCase("x-uue"))
return new UUDecoderStream(is);
else if (encoding.equalsIgnoreCase("binary") ||
encoding.equalsIgnoreCase("7bit") ||
encoding.equalsIgnoreCase("8bit"))
return is;
else {
if (!ignoreUnknownEncoding) {
throw new DecodingException("Unknown encoding: " + encoding);
}
return is;
}
}
}