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  package org.apache.commons.fileupload.util.mime;
    18
    19  import java.io.ByteArrayOutputStream;
    20  import java.io.IOException;
    21  import java.io.UnsupportedEncodingException;
    22  import java.util.HashMap;
    23  import java.util.Locale;
    24  import java.util.Map;
    25
    26  /**
    27   * Utility class to decode MIME texts.
    28   *
    29   * @since 1.3
    30   */
    31  public final class MimeUtility {
    32
    33      /**
    34       * The {@code US-ASCII} charset identifier constant.
    35       */
    36      private static final String US_ASCII_CHARSET = "US-ASCII";
    37
    38      /**
    39       * The marker to indicate text is encoded with BASE64 algorithm.
    40       */
    41      private static final String BASE64_ENCODING_MARKER = "B";
    42
    43      /**
    44       * The marker to indicate text is encoded with QuotedPrintable algorithm.
    45       */
    46      private static final String QUOTEDPRINTABLE_ENCODING_MARKER = "Q";
    47
    48      /**
    49       * If the text contains any encoded tokens, those tokens will be marked with "=?".
    50       */
    51      private static final String ENCODED_TOKEN_MARKER = "=?";
    52
    53      /**
    54       * If the text contains any encoded tokens, those tokens will terminate with "=?".
    55       */
    56      private static final String ENCODED_TOKEN_FINISHER = "?=";
    57
    58      /**
    59       * The linear whitespace chars sequence.
    60       */
    61      private static final String LINEAR_WHITESPACE = " \t\r\n";
    62
    63      /**
    64       * Mappings between MIME and Java charset.
    65       */
    66      private static final Map<String, String> MIME2JAVA = new HashMap<String, String>();
    67
    68      static {
    69          MIME2JAVA.put("iso-2022-cn", "ISO2022CN");
    70          MIME2JAVA.put("iso-2022-kr", "ISO2022KR");
    71          MIME2JAVA.put("utf-8", "UTF8");
    72          MIME2JAVA.put("utf8", "UTF8");
    73          MIME2JAVA.put("ja_jp.iso2022-7", "ISO2022JP");
    74          MIME2JAVA.put("ja_jp.eucjp", "EUCJIS");
    75          MIME2JAVA.put("euc-kr", "KSC5601");
    76          MIME2JAVA.put("euckr", "KSC5601");
    77          MIME2JAVA.put("us-ascii", "ISO-8859-1");
    78          MIME2JAVA.put("x-us-ascii", "ISO-8859-1");
    79      }
    80
    81      /**
    82       * Hidden constructor, this class must not be instantiated.
    83       */
    84      private MimeUtility() {
    85          // do nothing
    86      }
    87
    88      /**
    89       * Decode a string of text obtained from a mail header into
    90       * its proper form.  The text generally will consist of a
    91       * string of tokens, some of which may be encoded using
    92       * base64 encoding.
    93       *
    94       * @param text   The text to decode.
    95       *
    96       * @return The decoded text string.
    97       * @throws UnsupportedEncodingException if the detected encoding in the input text is not supported.
    98       */
    99      public static String decodeText(String text) throws UnsupportedEncodingException {
    100         // if the text contains any encoded tokens, those tokens will be marked with "=?".  If the
    101         // source string doesn't contain that sequent, no decoding is required.
    102         if (text.indexOf(ENCODED_TOKEN_MARKER) < 0) {
    103             return text;
    104         }
    105
    106         int offset = 0;
    107         int endOffset = text.length();
    108
    109         int startWhiteSpace = -1;
    110         int endWhiteSpace = -1;
    111
    112         StringBuilder decodedText = new StringBuilder(text.length());
    113
    114         boolean previousTokenEncoded = false;
    115
    116         while (offset < endOffset) {
    117             char ch = text.charAt(offset);
    118
    119             // is this a whitespace character?
    120             if (LINEAR_WHITESPACE.indexOf(ch) != -1) { // whitespace found
    121                 startWhiteSpace = offset;
    122                 while (offset < endOffset) {
    123                     // step over the white space characters.
    124                     ch = text.charAt(offset);
    125                     if (LINEAR_WHITESPACE.indexOf(ch) != -1) { // whitespace found
    126                         offset++;
    127                     } else {
    128                         // record the location of the first non lwsp and drop down to process the
    129                         // token characters.
    130                         endWhiteSpace = offset;
    131                         break;
    132                     }
    133                 }
    134             } else {
    135                 // we have a word token.  We need to scan over the word and then try to parse it.
    136                 int wordStart = offset;
    137
    138                 while (offset < endOffset) {
    139                     // step over the non white space characters.
    140                     ch = text.charAt(offset);
    141                     if (LINEAR_WHITESPACE.indexOf(ch) == -1) { // not white space
    142                         offset++;
    143                     } else {
    144                         break;
    145                     }
    146
    147                     //NB:  Trailing whitespace on these header strings will just be discarded.
    148                 }
    149                 // pull out the word token.
    150                 String word = text.substring(wordStart, offset);
    151                 // is the token encoded?  decode the word
    152                 if (word.startsWith(ENCODED_TOKEN_MARKER)) {
    153                     try {
    154                         // if this gives a parsing failure, treat it like a non-encoded word.
    155                         String decodedWord = decodeWord(word);
    156
    157                         // are any whitespace characters significant?  Append 'em if we've got 'em.
    158                         if (!previousTokenEncoded && startWhiteSpace != -1) {
    159                             decodedText.append(text.substring(startWhiteSpace, endWhiteSpace));
    160                             startWhiteSpace = -1;
    161                         }
    162                         // this is definitely a decoded token.
    163                         previousTokenEncoded = true;
    164                         // and add this to the text.
    165                         decodedText.append(decodedWord);
    166                         // we continue parsing from here...we allow parsing errors to fall through
    167                         // and get handled as normal text.
    168                         continue;
    169
    170                     } catch (ParseException e) {
    171                         // just ignore it, skip to next word
    172                     }
    173                 }
    174                 // this is a normal token, so it doesn't matter what the previous token was.  Add the white space
    175                 // if we have it.
    176                 if (startWhiteSpace != -1) {
    177                     decodedText.append(text.substring(startWhiteSpace, endWhiteSpace));
    178                     startWhiteSpace = -1;
    179                 }
    180                 // this is not a decoded token.
    181                 previousTokenEncoded = false;
    182                 decodedText.append(word);
    183             }
    184         }
    185
    186         return decodedText.toString();
    187     }
    188
    189     /**
    190      * Parse a string using the RFC 2047 rules for an "encoded-word"
    191      * type.  This encoding has the syntax:
    192      *
    193      * encoded-word = "=?" charset "?" encoding "?" encoded-text "?="
    194      *
    195      * @param word   The possibly encoded word value.
    196      *
    197      * @return The decoded word.
    198      * @throws ParseException
    199      * @throws UnsupportedEncodingException
    200      */
    201     private static String decodeWord(String word) throws ParseException, UnsupportedEncodingException {
    202         // encoded words start with the characters "=?".  If this not an encoded word, we throw a
    203         // ParseException for the caller.
    204
    205         if (!word.startsWith(ENCODED_TOKEN_MARKER)) {
    206             throw new ParseException("Invalid RFC 2047 encoded-word: " + word);
    207         }
    208
    209         int charsetPos = word.indexOf('?', 2);
    210         if (charsetPos == -1) {
    211             throw new ParseException("Missing charset in RFC 2047 encoded-word: " + word);
    212         }
    213
    214         // pull out the character set information (this is the MIME name at this point).
    215         String charset = word.substring(2, charsetPos).toLowerCase(Locale.ENGLISH);
    216
    217         // now pull out the encoding token the same way.
    218         int encodingPos = word.indexOf('?', charsetPos + 1);
    219         if (encodingPos == -1) {
    220             throw new ParseException("Missing encoding in RFC 2047 encoded-word: " + word);
    221         }
    222
    223         String encoding = word.substring(charsetPos + 1, encodingPos);
    224
    225         // and finally the encoded text.
    226         int encodedTextPos = word.indexOf(ENCODED_TOKEN_FINISHER, encodingPos + 1);
    227         if (encodedTextPos == -1) {
    228             throw new ParseException("Missing encoded text in RFC 2047 encoded-word: " + word);
    229         }
    230
    231         String encodedText = word.substring(encodingPos + 1, encodedTextPos);
    232
    233         // seems a bit silly to encode a null string, but easy to deal with.
    234         if (encodedText.length() == 0) {
    235             return "";
    236         }
    237
    238         try {
    239             // the decoder writes directly to an output stream.
    240             ByteArrayOutputStream out = new ByteArrayOutputStream(encodedText.length());
    241
    242             byte[] encodedData = encodedText.getBytes(US_ASCII_CHARSET);
    243
    244             // Base64 encoded?
    245             if (encoding.equals(BASE64_ENCODING_MARKER)) {
    246                 Base64Decoder.decode(encodedData, out);
    247             } else if (encoding.equals(QUOTEDPRINTABLE_ENCODING_MARKER)) { // maybe quoted printable.
    248                 QuotedPrintableDecoder.decode(encodedData, out);
    249             } else {
    250                 throw new UnsupportedEncodingException("Unknown RFC 2047 encoding: " + encoding);
    251             }
    252             // get the decoded byte data and convert into a string.
    253             byte[] decodedData = out.toByteArray();
    254             return new String(decodedData, javaCharset(charset));
    255         } catch (IOException e) {
    256             throw new UnsupportedEncodingException("Invalid RFC 2047 encoding");
    257         }
    258     }
    259
    260     /**
    261      * Translate a MIME standard character set name into the Java
    262      * equivalent.
    263      *
    264      * @param charset The MIME standard name.
    265      *
    266      * @return The Java equivalent for this name.
    267      */
    268     private static String javaCharset(String charset) {
    269         // nothing in, nothing out.
    270         if (charset == null) {
    271             return null;
    272         }
    273
    274         String mappedCharset = MIME2JAVA.get(charset.toLowerCase(Locale.ENGLISH));
    275         // if there is no mapping, then the original name is used.  Many of the MIME character set
    276         // names map directly back into Java.  The reverse isn't necessarily true.
    277         if (mappedCharset == null) {
    278             return charset;
    279         }
    280         return mappedCharset;
    281     }
    282
    283 }