View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.codec.net;
19  
20  import java.io.ByteArrayOutputStream;
21  import java.io.UnsupportedEncodingException;
22  import java.nio.charset.Charset;
23  import java.nio.charset.IllegalCharsetNameException;
24  import java.nio.charset.UnsupportedCharsetException;
25  import java.util.BitSet;
26  
27  import org.apache.commons.codec.BinaryDecoder;
28  import org.apache.commons.codec.BinaryEncoder;
29  import org.apache.commons.codec.Charsets;
30  import org.apache.commons.codec.DecoderException;
31  import org.apache.commons.codec.EncoderException;
32  import org.apache.commons.codec.StringDecoder;
33  import org.apache.commons.codec.StringEncoder;
34  import org.apache.commons.codec.binary.StringUtils;
35  
36  /**
37   * Codec for the Quoted-Printable section of <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a>.
38   * <p>
39   * The Quoted-Printable encoding is intended to represent data that largely consists of octets that correspond to
40   * printable characters in the ASCII character set. It encodes the data in such a way that the resulting octets are
41   * unlikely to be modified by mail transport. If the data being encoded are mostly ASCII text, the encoded form of the
42   * data remains largely recognizable by humans. A body which is entirely ASCII may also be encoded in Quoted-Printable
43   * to ensure the integrity of the data should the message pass through a character- translating, and/or line-wrapping
44   * gateway.
45   * <p>
46   * Note:
47   * <p>
48   * Rules #3, #4, and #5 of the quoted-printable spec are not implemented yet because the complete quoted-printable spec
49   * does not lend itself well into the byte[] oriented codec framework. Complete the codec once the streamable codec
50   * framework is ready. The motivation behind providing the codec in a partial form is that it can already come in handy
51   * for those applications that do not require quoted-printable line formatting (rules #3, #4, #5), for instance Q codec.
52   * <p>
53   * This class is immutable and thread-safe.
54   *
55   * @see <a href="http://www.ietf.org/rfc/rfc1521.txt"> RFC 1521 MIME (Multipurpose Internet Mail Extensions) Part One:
56   *          Mechanisms for Specifying and Describing the Format of Internet Message Bodies </a>
57   *
58   * @since 1.3
59   * @version $Id: QuotedPrintableCodec.java 1429868 2013-01-07 16:08:05Z ggregory $
60   */
61  public class QuotedPrintableCodec implements BinaryEncoder, BinaryDecoder, StringEncoder, StringDecoder {
62      /**
63       * The default charset used for string decoding and encoding.
64       */
65      private final Charset charset;
66  
67      /**
68       * BitSet of printable characters as defined in RFC 1521.
69       */
70      private static final BitSet PRINTABLE_CHARS = new BitSet(256);
71  
72      private static final byte ESCAPE_CHAR = '=';
73  
74      private static final byte TAB = 9;
75  
76      private static final byte SPACE = 32;
77      // Static initializer for printable chars collection
78      static {
79          // alpha characters
80          for (int i = 33; i <= 60; i++) {
81              PRINTABLE_CHARS.set(i);
82          }
83          for (int i = 62; i <= 126; i++) {
84              PRINTABLE_CHARS.set(i);
85          }
86          PRINTABLE_CHARS.set(TAB);
87          PRINTABLE_CHARS.set(SPACE);
88      }
89  
90      /**
91       * Default constructor, assumes default charset of {@link Charsets#UTF_8}
92       */
93      public QuotedPrintableCodec() {
94          this(Charsets.UTF_8);
95      }
96  
97      /**
98       * Constructor which allows for the selection of a default charset.
99       *
100      * @param charset
101      *            the default string charset to use.
102      * @since 1.7
103      */
104     public QuotedPrintableCodec(final Charset charset) {
105         this.charset = charset;
106     }
107 
108     /**
109      * Constructor which allows for the selection of a default charset.
110      *
111      * @param charsetName
112      *            the default string charset to use.
113      * @throws UnsupportedCharsetException
114      *             If no support for the named charset is available
115      *             in this instance of the Java virtual machine
116      * @throws IllegalArgumentException
117      *             If the given charsetName is null
118      * @throws IllegalCharsetNameException
119      *             If the given charset name is illegal
120      *
121      * @since 1.7 throws UnsupportedCharsetException if the named charset is unavailable
122      */
123     public QuotedPrintableCodec(final String charsetName)
124             throws IllegalCharsetNameException, IllegalArgumentException, UnsupportedCharsetException {
125         this(Charset.forName(charsetName));
126     }
127 
128     /**
129      * Encodes byte into its quoted-printable representation.
130      *
131      * @param b
132      *            byte to encode
133      * @param buffer
134      *            the buffer to write to
135      */
136     private static final void encodeQuotedPrintable(final int b, final ByteArrayOutputStream buffer) {
137         buffer.write(ESCAPE_CHAR);
138         final char hex1 = Character.toUpperCase(Character.forDigit((b >> 4) & 0xF, 16));
139         final char hex2 = Character.toUpperCase(Character.forDigit(b & 0xF, 16));
140         buffer.write(hex1);
141         buffer.write(hex2);
142     }
143 
144     /**
145      * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped.
146      * <p>
147      * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in
148      * RFC 1521 and is suitable for encoding binary data and unformatted text.
149      *
150      * @param printable
151      *            bitset of characters deemed quoted-printable
152      * @param bytes
153      *            array of bytes to be encoded
154      * @return array of bytes containing quoted-printable data
155      */
156     public static final byte[] encodeQuotedPrintable(BitSet printable, final byte[] bytes) {
157         if (bytes == null) {
158             return null;
159         }
160         if (printable == null) {
161             printable = PRINTABLE_CHARS;
162         }
163         final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
164         for (final byte c : bytes) {
165             int b = c;
166             if (b < 0) {
167                 b = 256 + b;
168             }
169             if (printable.get(b)) {
170                 buffer.write(b);
171             } else {
172                 encodeQuotedPrintable(b, buffer);
173             }
174         }
175         return buffer.toByteArray();
176     }
177 
178     /**
179      * Decodes an array quoted-printable characters into an array of original bytes. Escaped characters are converted
180      * back to their original representation.
181      * <p>
182      * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in
183      * RFC 1521.
184      *
185      * @param bytes
186      *            array of quoted-printable characters
187      * @return array of original bytes
188      * @throws DecoderException
189      *             Thrown if quoted-printable decoding is unsuccessful
190      */
191     public static final byte[] decodeQuotedPrintable(final byte[] bytes) throws DecoderException {
192         if (bytes == null) {
193             return null;
194         }
195         final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
196         for (int i = 0; i < bytes.length; i++) {
197             final int b = bytes[i];
198             if (b == ESCAPE_CHAR) {
199                 try {
200                     final int u = Utils.digit16(bytes[++i]);
201                     final int l = Utils.digit16(bytes[++i]);
202                     buffer.write((char) ((u << 4) + l));
203                 } catch (final ArrayIndexOutOfBoundsException e) {
204                     throw new DecoderException("Invalid quoted-printable encoding", e);
205                 }
206             } else {
207                 buffer.write(b);
208             }
209         }
210         return buffer.toByteArray();
211     }
212 
213     /**
214      * Encodes an array of bytes into an array of quoted-printable 7-bit characters. Unsafe characters are escaped.
215      * <p>
216      * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in
217      * RFC 1521 and is suitable for encoding binary data and unformatted text.
218      *
219      * @param bytes
220      *            array of bytes to be encoded
221      * @return array of bytes containing quoted-printable data
222      */
223     @Override
224     public byte[] encode(final byte[] bytes) {
225         return encodeQuotedPrintable(PRINTABLE_CHARS, bytes);
226     }
227 
228     /**
229      * Decodes an array of quoted-printable characters into an array of original bytes. Escaped characters are converted
230      * back to their original representation.
231      * <p>
232      * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in
233      * RFC 1521.
234      *
235      * @param bytes
236      *            array of quoted-printable characters
237      * @return array of original bytes
238      * @throws DecoderException
239      *             Thrown if quoted-printable decoding is unsuccessful
240      */
241     @Override
242     public byte[] decode(final byte[] bytes) throws DecoderException {
243         return decodeQuotedPrintable(bytes);
244     }
245 
246     /**
247      * Encodes a string into its quoted-printable form using the default string charset. Unsafe characters are escaped.
248      * <p>
249      * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in
250      * RFC 1521 and is suitable for encoding binary data.
251      *
252      * @param str
253      *            string to convert to quoted-printable form
254      * @return quoted-printable string
255      * @throws EncoderException
256      *             Thrown if quoted-printable encoding is unsuccessful
257      *
258      * @see #getCharset()
259      */
260     @Override
261     public String encode(final String str) throws EncoderException {
262         return this.encode(str, getCharset());
263     }
264 
265     /**
266      * Decodes a quoted-printable string into its original form using the specified string charset. Escaped characters
267      * are converted back to their original representation.
268      *
269      * @param str
270      *            quoted-printable string to convert into its original form
271      * @param charset
272      *            the original string charset
273      * @return original string
274      * @throws DecoderException
275      *             Thrown if quoted-printable decoding is unsuccessful
276      * @since 1.7
277      */
278     public String decode(final String str, final Charset charset) throws DecoderException {
279         if (str == null) {
280             return null;
281         }
282         return new String(this.decode(StringUtils.getBytesUsAscii(str)), charset);
283     }
284 
285     /**
286      * Decodes a quoted-printable string into its original form using the specified string charset. Escaped characters
287      * are converted back to their original representation.
288      *
289      * @param str
290      *            quoted-printable string to convert into its original form
291      * @param charset
292      *            the original string charset
293      * @return original string
294      * @throws DecoderException
295      *             Thrown if quoted-printable decoding is unsuccessful
296      * @throws UnsupportedEncodingException
297      *             Thrown if charset is not supported
298      */
299     public String decode(final String str, final String charset) throws DecoderException, UnsupportedEncodingException {
300         if (str == null) {
301             return null;
302         }
303         return new String(decode(StringUtils.getBytesUsAscii(str)), charset);
304     }
305 
306     /**
307      * Decodes a quoted-printable string into its original form using the default string charset. Escaped characters are
308      * converted back to their original representation.
309      *
310      * @param str
311      *            quoted-printable string to convert into its original form
312      * @return original string
313      * @throws DecoderException
314      *             Thrown if quoted-printable decoding is unsuccessful. Thrown if charset is not supported.
315      * @see #getCharset()
316      */
317     @Override
318     public String decode(final String str) throws DecoderException {
319         return this.decode(str, this.getCharset());
320     }
321 
322     /**
323      * Encodes an object into its quoted-printable safe form. Unsafe characters are escaped.
324      *
325      * @param obj
326      *            string to convert to a quoted-printable form
327      * @return quoted-printable object
328      * @throws EncoderException
329      *             Thrown if quoted-printable encoding is not applicable to objects of this type or if encoding is
330      *             unsuccessful
331      */
332     @Override
333     public Object encode(final Object obj) throws EncoderException {
334         if (obj == null) {
335             return null;
336         } else if (obj instanceof byte[]) {
337             return encode((byte[]) obj);
338         } else if (obj instanceof String) {
339             return encode((String) obj);
340         } else {
341             throw new EncoderException("Objects of type " +
342                   obj.getClass().getName() +
343                   " cannot be quoted-printable encoded");
344         }
345     }
346 
347     /**
348      * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original
349      * representation.
350      *
351      * @param obj
352      *            quoted-printable object to convert into its original form
353      * @return original object
354      * @throws DecoderException
355      *             Thrown if the argument is not a <code>String</code> or <code>byte[]</code>. Thrown if a failure
356      *             condition is encountered during the decode process.
357      */
358     @Override
359     public Object decode(final Object obj) throws DecoderException {
360         if (obj == null) {
361             return null;
362         } else if (obj instanceof byte[]) {
363             return decode((byte[]) obj);
364         } else if (obj instanceof String) {
365             return decode((String) obj);
366         } else {
367             throw new DecoderException("Objects of type " +
368                   obj.getClass().getName() +
369                   " cannot be quoted-printable decoded");
370         }
371     }
372 
373     /**
374      * Gets the default charset name used for string decoding and encoding.
375      *
376      * @return the default charset name
377      * @since 1.7
378      */
379     public Charset getCharset() {
380         return this.charset;
381     }
382 
383     /**
384      * Gets the default charset name used for string decoding and encoding.
385      *
386      * @return the default charset name
387      */
388     public String getDefaultCharset() {
389         return this.charset.name();
390     }
391 
392     /**
393      * Encodes a string into its quoted-printable form using the specified charset. Unsafe characters are escaped.
394      * <p>
395      * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in
396      * RFC 1521 and is suitable for encoding binary data and unformatted text.
397      *
398      * @param str
399      *            string to convert to quoted-printable form
400      * @param charset
401      *            the charset for str
402      * @return quoted-printable string
403      * @since 1.7
404      */
405     public String encode(final String str, final Charset charset) {
406         if (str == null) {
407             return null;
408         }
409         return StringUtils.newStringUsAscii(this.encode(str.getBytes(charset)));
410     }
411 
412     /**
413      * Encodes a string into its quoted-printable form using the specified charset. Unsafe characters are escaped.
414      * <p>
415      * This function implements a subset of quoted-printable encoding specification (rule #1 and rule #2) as defined in
416      * RFC 1521 and is suitable for encoding binary data and unformatted text.
417      *
418      * @param str
419      *            string to convert to quoted-printable form
420      * @param charset
421      *            the charset for str
422      * @return quoted-printable string
423      * @throws UnsupportedEncodingException
424      *             Thrown if the charset is not supported
425      */
426     public String encode(final String str, final String charset) throws UnsupportedEncodingException {
427         if (str == null) {
428             return null;
429         }
430         return StringUtils.newStringUsAscii(encode(str.getBytes(charset)));
431     }
432 }