Package: MimeUtility

MimeUtility

name	instruction	branch	complexity	line	method
decode(InputStream, String)	M: 28 C: 31 53%	M: 11 C: 7 39%	M: 8 C: 2 20%	M: 7 C: 8 53%	M: 0 C: 1 100%
static {...}	M: 0 C: 5 100%	M: 0 C: 0 100%	M: 0 C: 1 100%	M: 0 C: 2 100%	M: 0 C: 1 100%

Coverage

1: /*
2: * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Distribution License v. 1.0, which is available at
6: * http://www.eclipse.org/org/documents/edl-v10.php.
7: *
8: * SPDX-License-Identifier: BSD-3-Clause
9: */
10:
11: package org.jvnet.mimepull;
12:
13: import java.io.*;
14:
15:
16: /**
17: * This is a utility class that provides various MIME related
18: * functionality. <p>
19: *
20: * There are a set of methods to encode and decode MIME headers as
21: * per RFC 2047. Note that, in general, these methods are
22: * <strong>not</strong> needed when using methods such as
23: * <code>setSubject</code> and <code>setRecipients</code> JavaMail
24: * will automatically encode and decode data when using these "higher
25: * level" methods. The methods below are only needed when maniuplating
26: * raw MIME headers using <code>setHeader</code> and <code>getHeader</code>
27: * methods. A brief description on handling such headers is given below: <p>
28: *
29: * RFC 822 mail headers <strong>must</strong> contain only US-ASCII
30: * characters. Headers that contain non US-ASCII characters must be
31: * encoded so that they contain only US-ASCII characters. Basically,
32: * this process involves using either BASE64 or QP to encode certain
33: * characters. RFC 2047 describes this in detail. <p>
34: *
35: * In Java, Strings contain (16 bit) Unicode characters. ASCII is a
36: * subset of Unicode (and occupies the range 0 - 127). A String
37: * that contains only ASCII characters is already mail-safe. If the
38: * String contains non US-ASCII characters, it must be encoded. An
39: * additional complexity in this step is that since Unicode is not
40: * yet a widely used charset, one might want to first charset-encode
41: * the String into another charset and then do the transfer-encoding.
42: * <p>
43: * Note that to get the actual bytes of a mail-safe String (say,
44: * for sending over SMTP), one must do
45: * <blockquote><pre>
46: *
47: *        byte[] bytes = string.getBytes("iso-8859-1");        
48: *
49: * </pre></blockquote><p>
50: *
51: * The <code>setHeader</code> and <code>addHeader</code> methods
52: * on MimeMessage and MimeBodyPart assume that the given header values
53: * are Unicode strings that contain only US-ASCII characters. Hence
54: * the callers of those methods must insure that the values they pass
55: * do not contain non US-ASCII characters. The methods in this class
56: * help do this. <p>
57: *
58: * The <code>getHeader</code> family of methods on MimeMessage and
59: * MimeBodyPart return the raw header value. These might be encoded
60: * as per RFC 2047, and if so, must be decoded into Unicode Strings.
61: * The methods in this class help to do this. <p>
62: *
63: * Several System properties control strict conformance to the MIME
64: * spec. Note that these are not session properties but must be set
65: * globally as System properties. <p>
66: *
67: * The <code>mail.mime.decodetext.strict</code> property controls
68: * decoding of MIME encoded words. The MIME spec requires that encoded
69: * words start at the beginning of a whitespace separated word. Some
70: * mailers incorrectly include encoded words in the middle of a word.
71: * If the <code>mail.mime.decodetext.strict</code> System property is
72: * set to <code>"false"</code>, an attempt will be made to decode these
73: * illegal encoded words. The default is true. <p>
74: *
75: * The <code>mail.mime.encodeeol.strict</code> property controls the
76: * choice of Content-Transfer-Encoding for MIME parts that are not of
77: * type "text". Often such parts will contain textual data for which
78: * an encoding that allows normal end of line conventions is appropriate.
79: * In rare cases, such a part will appear to contain entirely textual
80: * data, but will require an encoding that preserves CR and LF characters
81: * without change. If the <code>mail.mime.encodeeol.strict</code>
82: * System property is set to <code>"true"</code>, such an encoding will
83: * be used when necessary. The default is false. <p>
84: *
85: * In addition, the <code>mail.mime.charset</code> System property can
86: * be used to specify the default MIME charset to use for encoded words
87: * and text parts that don't otherwise specify a charset. Normally, the
88: * default MIME charset is derived from the default Java charset, as
89: * specified in the <code>file.encoding</code> System property. Most
90: * applications will have no need to explicitly set the default MIME
91: * charset. In cases where the default MIME charset to be used for
92: * mail messages is different than the charset used for files stored on
93: * the system, this property should be set. <p>
94: *
95: * The current implementation also supports the following System property.
96: * <p>
97: * The <code>mail.mime.ignoreunknownencoding</code> property controls
98: * whether unknown values in the <code>Content-Transfer-Encoding</code>
99: * header, as passed to the <code>decode</code> method, cause an exception.
100: * If set to <code>"true"</code>, unknown values are ignored and 8bit
101: * encoding is assumed. Otherwise, unknown values cause a MessagingException
102: * to be thrown.
103: *
104: * @author John Mani
105: * @author Bill Shannon
106: */
107:
108: /* FROM mail.jar */
109: final class MimeUtility {
110:
111: // This class cannot be instantiated
112: private MimeUtility() { }
113:
114: private static final boolean ignoreUnknownEncoding =
115:         PropUtil.getBooleanSystemProperty(
116:          "mail.mime.ignoreunknownencoding", false);
117:
118: /**
119: * Decode the given input stream. The Input stream returned is
120: * the decoded input stream. All the encodings defined in RFC 2045
121: * are supported here. They include "base64", "quoted-printable",
122: * "7bit", "8bit", and "binary". In addition, "uuencode" is also
123: * supported. <p>
124: *
125: * In the current implementation, if the
126: * <code>mail.mime.ignoreunknownencoding</code> system property is set to
127: * <code>"true"</code>, unknown encoding values are ignored and the
128: * original InputStream is returned.
129: *
130: * @param        is                input stream
131: * @param        encoding        the encoding of the stream.
132: * @return                        decoded input stream.
133: * @exception DecodingException        if the encoding is unknown
134: */
135: public static InputStream decode(InputStream is, String encoding)
136:                 throws DecodingException {
137:•        if (encoding.equalsIgnoreCase("base64"))
138:          return new BASE64DecoderStream(is);
139:•        else if (encoding.equalsIgnoreCase("quoted-printable"))
140:          return new QPDecoderStream(is);
141:•        else if (encoding.equalsIgnoreCase("uuencode") ||
142:•                 encoding.equalsIgnoreCase("x-uuencode") ||
143:•                 encoding.equalsIgnoreCase("x-uue"))
144:          return new UUDecoderStream(is);
145:•        else if (encoding.equalsIgnoreCase("binary") ||
146:•                 encoding.equalsIgnoreCase("7bit") ||
147:•                 encoding.equalsIgnoreCase("8bit"))
148:          return is;
149:         else {
150:•         if (!ignoreUnknownEncoding) {
151: throw new DecodingException("Unknown encoding: " + encoding);
152: }
153:          return is;
154:         }
155: }
156: }