Fri, 04 Oct 2013 16:21:34 +0100
8025054: Update JAX-WS RI integration to 2.2.9-b130926.1035
Reviewed-by: chegar
1 /*
2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 package com.sun.xml.internal.org.jvnet.mimepull;
28 import java.io.*;
31 /**
32 * This is a utility class that provides various MIME related
33 * functionality. <p>
34 *
35 * There are a set of methods to encode and decode MIME headers as
36 * per RFC 2047. Note that, in general, these methods are
37 * <strong>not</strong> needed when using methods such as
38 * <code>setSubject</code> and <code>setRecipients</code>; JavaMail
39 * will automatically encode and decode data when using these "higher
40 * level" methods. The methods below are only needed when maniuplating
41 * raw MIME headers using <code>setHeader</code> and <code>getHeader</code>
42 * methods. A brief description on handling such headers is given below: <p>
43 *
44 * RFC 822 mail headers <strong>must</strong> contain only US-ASCII
45 * characters. Headers that contain non US-ASCII characters must be
46 * encoded so that they contain only US-ASCII characters. Basically,
47 * this process involves using either BASE64 or QP to encode certain
48 * characters. RFC 2047 describes this in detail. <p>
49 *
50 * In Java, Strings contain (16 bit) Unicode characters. ASCII is a
51 * subset of Unicode (and occupies the range 0 - 127). A String
52 * that contains only ASCII characters is already mail-safe. If the
53 * String contains non US-ASCII characters, it must be encoded. An
54 * additional complexity in this step is that since Unicode is not
55 * yet a widely used charset, one might want to first charset-encode
56 * the String into another charset and then do the transfer-encoding.
57 * <p>
58 * Note that to get the actual bytes of a mail-safe String (say,
59 * for sending over SMTP), one must do
60 * <p><blockquote><pre>
61 *
62 * byte[] bytes = string.getBytes("iso-8859-1");
63 *
64 * </pre></blockquote><p>
65 *
66 * The <code>setHeader</code> and <code>addHeader</code> methods
67 * on MimeMessage and MimeBodyPart assume that the given header values
68 * are Unicode strings that contain only US-ASCII characters. Hence
69 * the callers of those methods must insure that the values they pass
70 * do not contain non US-ASCII characters. The methods in this class
71 * help do this. <p>
72 *
73 * The <code>getHeader</code> family of methods on MimeMessage and
74 * MimeBodyPart return the raw header value. These might be encoded
75 * as per RFC 2047, and if so, must be decoded into Unicode Strings.
76 * The methods in this class help to do this. <p>
77 *
78 * Several System properties control strict conformance to the MIME
79 * spec. Note that these are not session properties but must be set
80 * globally as System properties. <p>
81 *
82 * The <code>mail.mime.decodetext.strict</code> property controls
83 * decoding of MIME encoded words. The MIME spec requires that encoded
84 * words start at the beginning of a whitespace separated word. Some
85 * mailers incorrectly include encoded words in the middle of a word.
86 * If the <code>mail.mime.decodetext.strict</code> System property is
87 * set to <code>"false"</code>, an attempt will be made to decode these
88 * illegal encoded words. The default is true. <p>
89 *
90 * The <code>mail.mime.encodeeol.strict</code> property controls the
91 * choice of Content-Transfer-Encoding for MIME parts that are not of
92 * type "text". Often such parts will contain textual data for which
93 * an encoding that allows normal end of line conventions is appropriate.
94 * In rare cases, such a part will appear to contain entirely textual
95 * data, but will require an encoding that preserves CR and LF characters
96 * without change. If the <code>mail.mime.encodeeol.strict</code>
97 * System property is set to <code>"true"</code>, such an encoding will
98 * be used when necessary. The default is false. <p>
99 *
100 * In addition, the <code>mail.mime.charset</code> System property can
101 * be used to specify the default MIME charset to use for encoded words
102 * and text parts that don't otherwise specify a charset. Normally, the
103 * default MIME charset is derived from the default Java charset, as
104 * specified in the <code>file.encoding</code> System property. Most
105 * applications will have no need to explicitly set the default MIME
106 * charset. In cases where the default MIME charset to be used for
107 * mail messages is different than the charset used for files stored on
108 * the system, this property should be set. <p>
109 *
110 * The current implementation also supports the following System property.
111 * <p>
112 * The <code>mail.mime.ignoreunknownencoding</code> property controls
113 * whether unknown values in the <code>Content-Transfer-Encoding</code>
114 * header, as passed to the <code>decode</code> method, cause an exception.
115 * If set to <code>"true"</code>, unknown values are ignored and 8bit
116 * encoding is assumed. Otherwise, unknown values cause a MessagingException
117 * to be thrown.
118 *
119 * @author John Mani
120 * @author Bill Shannon
121 */
123 /* FROM mail.jar */
124 final class MimeUtility {
126 // This class cannot be instantiated
127 private MimeUtility() { }
129 private static final boolean ignoreUnknownEncoding =
130 PropUtil.getBooleanSystemProperty(
131 "mail.mime.ignoreunknownencoding", false);
133 /**
134 * Decode the given input stream. The Input stream returned is
135 * the decoded input stream. All the encodings defined in RFC 2045
136 * are supported here. They include "base64", "quoted-printable",
137 * "7bit", "8bit", and "binary". In addition, "uuencode" is also
138 * supported. <p>
139 *
140 * In the current implementation, if the
141 * <code>mail.mime.ignoreunknownencoding</code> system property is set to
142 * <code>"true"</code>, unknown encoding values are ignored and the
143 * original InputStream is returned.
144 *
145 * @param is input stream
146 * @param encoding the encoding of the stream.
147 * @return decoded input stream.
148 * @exception MessagingException if the encoding is unknown
149 */
150 public static InputStream decode(InputStream is, String encoding)
151 throws DecodingException {
152 if (encoding.equalsIgnoreCase("base64"))
153 return new BASE64DecoderStream(is);
154 else if (encoding.equalsIgnoreCase("quoted-printable"))
155 return new QPDecoderStream(is);
156 else if (encoding.equalsIgnoreCase("uuencode") ||
157 encoding.equalsIgnoreCase("x-uuencode") ||
158 encoding.equalsIgnoreCase("x-uue"))
159 return new UUDecoderStream(is);
160 else if (encoding.equalsIgnoreCase("binary") ||
161 encoding.equalsIgnoreCase("7bit") ||
162 encoding.equalsIgnoreCase("8bit"))
163 return is;
164 else {
165 if (!ignoreUnknownEncoding) {
166 throw new DecodingException("Unknown encoding: " + encoding);
167 }
168 return is;
169 }
170 }
171 }