QCodec.java

  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.  */

  18. package org.apache.commons.codec.net;

  20. import java.io.UnsupportedEncodingException;
  21. import java.nio.charset.Charset;
  22. import java.util.BitSet;

  24. import org.apache.commons.codec.Charsets;
  25. import org.apache.commons.codec.DecoderException;
  26. import org.apache.commons.codec.EncoderException;
  27. import org.apache.commons.codec.StringDecoder;
  28. import org.apache.commons.codec.StringEncoder;

  30. /**
  31.  * Similar to the Quoted-Printable content-transfer-encoding defined in
  32.  * <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a> and designed to allow text containing mostly ASCII
  33.  * characters to be decipherable on an ASCII terminal without decoding.
  34.  * <p>
  35.  * <a href="http://www.ietf.org/rfc/rfc1522.txt">RFC 1522</a> describes techniques to allow the encoding of non-ASCII
  36.  * text in various portions of a RFC 822 [2] message header, in a manner which is unlikely to confuse existing message
  37.  * handling software.
  38.  * <p>
  39.  * This class is conditionally thread-safe.
  40.  * The instance field {@link #encodeBlanks} is mutable {@link #setEncodeBlanks(boolean)}
  41.  * but is not volatile, and accesses are not synchronised.
  42.  * If an instance of the class is shared between threads, the caller needs to ensure that suitable synchronisation
  43.  * is used to ensure safe publication of the value between threads, and must not invoke
  44.  * {@link #setEncodeBlanks(boolean)} after initial setup.
  45.  *
  46.  * @see <a href="http://www.ietf.org/rfc/rfc1522.txt">MIME (Multipurpose Internet Mail Extensions) Part Two: Message
  47.  *          Header Extensions for Non-ASCII Text</a>
  48.  *
  49.  * @since 1.3
  50.  * @version $Id: QCodec.java 1619948 2014-08-22 22:53:55Z ggregory $
  51.  */
  52. public class QCodec extends RFC1522Codec implements StringEncoder, StringDecoder {
  53.     /**
  54.      * The default charset used for string decoding and encoding.
  55.      */
  56.     private final Charset charset;

  58.     /**
  59.      * BitSet of printable characters as defined in RFC 1522.
  60.      */
  61.     private static final BitSet PRINTABLE_CHARS = new BitSet(256);
  62.     // Static initializer for printable chars collection
  63.     static {
  64.         // alpha characters
  65.         PRINTABLE_CHARS.set(' ');
  66.         PRINTABLE_CHARS.set('!');
  67.         PRINTABLE_CHARS.set('"');
  68.         PRINTABLE_CHARS.set('#');
  69.         PRINTABLE_CHARS.set('$');
  70.         PRINTABLE_CHARS.set('%');
  71.         PRINTABLE_CHARS.set('&');
  72.         PRINTABLE_CHARS.set('\'');
  73.         PRINTABLE_CHARS.set('(');
  74.         PRINTABLE_CHARS.set(')');
  75.         PRINTABLE_CHARS.set('*');
  76.         PRINTABLE_CHARS.set('+');
  77.         PRINTABLE_CHARS.set(',');
  78.         PRINTABLE_CHARS.set('-');
  79.         PRINTABLE_CHARS.set('.');
  80.         PRINTABLE_CHARS.set('/');
  81.         for (int i = '0'; i <= '9'; i++) {
  82.             PRINTABLE_CHARS.set(i);
  83.         }
  84.         PRINTABLE_CHARS.set(':');
  85.         PRINTABLE_CHARS.set(';');
  86.         PRINTABLE_CHARS.set('<');
  87.         PRINTABLE_CHARS.set('>');
  88.         PRINTABLE_CHARS.set('@');
  89.         for (int i = 'A'; i <= 'Z'; i++) {
  90.             PRINTABLE_CHARS.set(i);
  91.         }
  92.         PRINTABLE_CHARS.set('[');
  93.         PRINTABLE_CHARS.set('\\');
  94.         PRINTABLE_CHARS.set(']');
  95.         PRINTABLE_CHARS.set('^');
  96.         PRINTABLE_CHARS.set('`');
  97.         for (int i = 'a'; i <= 'z'; i++) {
  98.             PRINTABLE_CHARS.set(i);
  99.         }
  100.         PRINTABLE_CHARS.set('{');
  101.         PRINTABLE_CHARS.set('|');
  102.         PRINTABLE_CHARS.set('}');
  103.         PRINTABLE_CHARS.set('~');
  104.     }

  106.     private static final byte BLANK = 32;

  108.     private static final byte UNDERSCORE = 95;

  110.     private boolean encodeBlanks = false;

  112.     /**
  113.      * Default constructor.
  114.      */
  115.     public QCodec() {
  116.         this(Charsets.UTF_8);
  117.     }

  119.     /**
  120.      * Constructor which allows for the selection of a default charset.
  121.      *
  122.      * @param charset
  123.      *            the default string charset to use.
  124.      *
  125.      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  126.      * @since 1.7
  127.      */
  128.     public QCodec(final Charset charset) {
  129.         super();
  130.         this.charset = charset;
  131.     }

  133.     /**
  134.      * Constructor which allows for the selection of a default charset.
  135.      *
  136.      * @param charsetName
  137.      *            the charset to use.
  138.      * @throws java.nio.charset.UnsupportedCharsetException
  139.      *             If the named charset is unavailable
  140.      * @since 1.7 throws UnsupportedCharsetException if the named charset is unavailable
  141.      * @see <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
  142.      */
  143.     public QCodec(final String charsetName) {
  144.         this(Charset.forName(charsetName));
  145.     }

  147.     @Override
  148.     protected String getEncoding() {
  149.         return "Q";
  150.     }

  152.     @Override
  153.     protected byte[] doEncoding(final byte[] bytes) {
  154.         if (bytes == null) {
  155.             return null;
  156.         }
  157.         final byte[] data = QuotedPrintableCodec.encodeQuotedPrintable(PRINTABLE_CHARS, bytes);
  158.         if (this.encodeBlanks) {
  159.             for (int i = 0; i < data.length; i++) {
  160.                 if (data[i] == BLANK) {
  161.                     data[i] = UNDERSCORE;
  162.                 }
  163.             }
  164.         }
  165.         return data;
  166.     }

  168.     @Override
  169.     protected byte[] doDecoding(final byte[] bytes) throws DecoderException {
  170.         if (bytes == null) {
  171.             return null;
  172.         }
  173.         boolean hasUnderscores = false;
  174.         for (final byte b : bytes) {
  175.             if (b == UNDERSCORE) {
  176.                 hasUnderscores = true;
  177.                 break;
  178.             }
  179.         }
  180.         if (hasUnderscores) {
  181.             final byte[] tmp = new byte[bytes.length];
  182.             for (int i = 0; i < bytes.length; i++) {
  183.                 final byte b = bytes[i];
  184.                 if (b != UNDERSCORE) {
  185.                     tmp[i] = b;
  186.                 } else {
  187.                     tmp[i] = BLANK;
  188.                 }
  189.             }
  190.             return QuotedPrintableCodec.decodeQuotedPrintable(tmp);
  191.         }
  192.         return QuotedPrintableCodec.decodeQuotedPrintable(bytes);
  193.     }

  195.     /**
  196.      * Encodes a string into its quoted-printable form using the specified charset. Unsafe characters are escaped.
  197.      *
  198.      * @param str
  199.      *            string to convert to quoted-printable form
  200.      * @param charset
  201.      *            the charset for str
  202.      * @return quoted-printable string
  203.      * @throws EncoderException
  204.      *             thrown if a failure condition is encountered during the encoding process.
  205.      * @since 1.7
  206.      */
  207.     public String encode(final String str, final Charset charset) throws EncoderException {
  208.         if (str == null) {
  209.             return null;
  210.         }
  211.         return encodeText(str, charset);
  212.     }

  214.     /**
  215.      * Encodes a string into its quoted-printable form using the specified charset. Unsafe characters are escaped.
  216.      *
  217.      * @param str
  218.      *            string to convert to quoted-printable form
  219.      * @param charset
  220.      *            the charset for str
  221.      * @return quoted-printable string
  222.      * @throws EncoderException
  223.      *             thrown if a failure condition is encountered during the encoding process.
  224.      */
  225.     public String encode(final String str, final String charset) throws EncoderException {
  226.         if (str == null) {
  227.             return null;
  228.         }
  229.         try {
  230.             return encodeText(str, charset);
  231.         } catch (final UnsupportedEncodingException e) {
  232.             throw new EncoderException(e.getMessage(), e);
  233.         }
  234.     }

  236.     /**
  237.      * Encodes a string into its quoted-printable form using the default charset. Unsafe characters are escaped.
  238.      *
  239.      * @param str
  240.      *            string to convert to quoted-printable form
  241.      * @return quoted-printable string
  242.      * @throws EncoderException
  243.      *             thrown if a failure condition is encountered during the encoding process.
  244.      */
  245.     @Override
  246.     public String encode(final String str) throws EncoderException {
  247.         if (str == null) {
  248.             return null;
  249.         }
  250.         return encode(str, getCharset());
  251.     }

  253.     /**
  254.      * Decodes a quoted-printable string into its original form. Escaped characters are converted back to their original
  255.      * representation.
  256.      *
  257.      * @param str
  258.      *            quoted-printable string to convert into its original form
  259.      * @return original string
  260.      * @throws DecoderException
  261.      *             A decoder exception is thrown if a failure condition is encountered during the decode process.
  262.      */
  263.     @Override
  264.     public String decode(final String str) throws DecoderException {
  265.         if (str == null) {
  266.             return null;
  267.         }
  268.         try {
  269.             return decodeText(str);
  270.         } catch (final UnsupportedEncodingException e) {
  271.             throw new DecoderException(e.getMessage(), e);
  272.         }
  273.     }

  275.     /**
  276.      * Encodes an object into its quoted-printable form using the default charset. Unsafe characters are escaped.
  277.      *
  278.      * @param obj
  279.      *            object to convert to quoted-printable form
  280.      * @return quoted-printable object
  281.      * @throws EncoderException
  282.      *             thrown if a failure condition is encountered during the encoding process.
  283.      */
  284.     @Override
  285.     public Object encode(final Object obj) throws EncoderException {
  286.         if (obj == null) {
  287.             return null;
  288.         } else if (obj instanceof String) {
  289.             return encode((String) obj);
  290.         } else {
  291.             throw new EncoderException("Objects of type " +
  292.                   obj.getClass().getName() +
  293.                   " cannot be encoded using Q codec");
  294.         }
  295.     }

  297.     /**
  298.      * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original
  299.      * representation.
  300.      *
  301.      * @param obj
  302.      *            quoted-printable object to convert into its original form
  303.      * @return original object
  304.      * @throws DecoderException
  305.      *             Thrown if the argument is not a <code>String</code>. Thrown if a failure condition is encountered
  306.      *             during the decode process.
  307.      */
  308.     @Override
  309.     public Object decode(final Object obj) throws DecoderException {
  310.         if (obj == null) {
  311.             return null;
  312.         } else if (obj instanceof String) {
  313.             return decode((String) obj);
  314.         } else {
  315.             throw new DecoderException("Objects of type " +
  316.                   obj.getClass().getName() +
  317.                   " cannot be decoded using Q codec");
  318.         }
  319.     }

  321.     /**
  322.      * Gets the default charset name used for string decoding and encoding.
  323.      *
  324.      * @return the default charset name
  325.      * @since 1.7
  326.      */
  327.     public Charset getCharset() {
  328.         return this.charset;
  329.     }

  331.     /**
  332.      * Gets the default charset name used for string decoding and encoding.
  333.      *
  334.      * @return the default charset name
  335.      */
  336.     public String getDefaultCharset() {
  337.         return this.charset.name();
  338.     }

  340.     /**
  341.      * Tests if optional transformation of SPACE characters is to be used
  342.      *
  343.      * @return <code>true</code> if SPACE characters are to be transformed, <code>false</code> otherwise
  344.      */
  345.     public boolean isEncodeBlanks() {
  346.         return this.encodeBlanks;
  347.     }

  349.     /**
  350.      * Defines whether optional transformation of SPACE characters is to be used
  351.      *
  352.      * @param b
  353.      *            <code>true</code> if SPACE characters are to be transformed, <code>false</code> otherwise
  354.      */
  355.     public void setEncodeBlanks(final boolean b) {
  356.         this.encodeBlanks = b;
  357.     }
  358. }
Created with JaCoCo 0.7.7.201606060606