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.  *      https://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.nio.charset.StandardCharsets;
  23. import java.nio.charset.UnsupportedCharsetException;
  24. import java.util.BitSet;

  26. import org.apache.commons.codec.DecoderException;
  27. import org.apache.commons.codec.EncoderException;
  28. import org.apache.commons.codec.StringDecoder;
  29. import org.apache.commons.codec.StringEncoder;

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

  60.     // Static initializer for printable chars collection
  61.     static {
  62.         // alpha characters
  63.         PRINTABLE_CHARS.set(' ');
  64.         PRINTABLE_CHARS.set('!');
  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.         for (int i = '0'; i <= '9'; i++) {
  80.             PRINTABLE_CHARS.set(i);
  81.         }
  82.         PRINTABLE_CHARS.set(':');
  83.         PRINTABLE_CHARS.set(';');
  84.         PRINTABLE_CHARS.set('<');
  85.         PRINTABLE_CHARS.set('>');
  86.         PRINTABLE_CHARS.set('@');
  87.         for (int i = 'A'; i <= 'Z'; i++) {
  88.             PRINTABLE_CHARS.set(i);
  89.         }
  90.         PRINTABLE_CHARS.set('[');
  91.         PRINTABLE_CHARS.set('\\');
  92.         PRINTABLE_CHARS.set(']');
  93.         PRINTABLE_CHARS.set('^');
  94.         PRINTABLE_CHARS.set('`');
  95.         for (int i = 'a'; i <= 'z'; i++) {
  96.             PRINTABLE_CHARS.set(i);
  97.         }
  98.         PRINTABLE_CHARS.set('{');
  99.         PRINTABLE_CHARS.set('|');
  100.         PRINTABLE_CHARS.set('}');
  101.         PRINTABLE_CHARS.set('~');
  102.     }
  103.     private static final byte SPACE = 32;

  105.     private static final byte UNDERSCORE = 95;

  107.     private boolean encodeBlanks;

  109.     /**
  110.      * Default constructor.
  111.      */
  112.     public QCodec() {
  113.         this(StandardCharsets.UTF_8);
  114.     }

  116.     /**
  117.      * Constructor which allows for the selection of a default Charset.
  118.      *
  119.      * @param charset
  120.      *            the default string Charset to use.
  121.      *
  122.      * @see Charset
  123.      * @since 1.7
  124.      */
  125.     public QCodec(final Charset charset) {
  126.         super(charset);
  127.     }

  129.     /**
  130.      * Constructor which allows for the selection of a default Charset.
  131.      *
  132.      * @param charsetName
  133.      *            the Charset to use.
  134.      * @throws java.nio.charset.UnsupportedCharsetException
  135.      *             If the named Charset is unavailable
  136.      * @since 1.7 throws UnsupportedCharsetException if the named Charset is unavailable
  137.      * @see Charset
  138.      */
  139.     public QCodec(final String charsetName) {
  140.         this(Charset.forName(charsetName));
  141.     }

  143.     /**
  144.      * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original
  145.      * representation.
  146.      *
  147.      * @param obj
  148.      *            quoted-printable object to convert into its original form
  149.      * @return original object
  150.      * @throws DecoderException
  151.      *             Thrown if the argument is not a {@code String}. Thrown if a failure condition is encountered
  152.      *             during the decode process.
  153.      */
  154.     @Override
  155.     public Object decode(final Object obj) throws DecoderException {
  156.         if (obj == null) {
  157.             return null;
  158.         }
  159.         if (obj instanceof String) {
  160.             return decode((String) obj);
  161.         }
  162.         throw new DecoderException("Objects of type " + obj.getClass().getName() + " cannot be decoded using Q codec");
  163.     }

  165.     /**
  166.      * Decodes a quoted-printable string into its original form. Escaped characters are converted back to their original
  167.      * representation.
  168.      *
  169.      * @param str
  170.      *            quoted-printable string to convert into its original form
  171.      * @return original string
  172.      * @throws DecoderException
  173.      *             A decoder exception is thrown if a failure condition is encountered during the decode process.
  174.      */
  175.     @Override
  176.     public String decode(final String str) throws DecoderException {
  177.         try {
  178.             return decodeText(str);
  179.         } catch (final UnsupportedEncodingException e) {
  180.             throw new DecoderException(e.getMessage(), e);
  181.         }
  182.     }

  184.     @Override
  185.     protected byte[] doDecoding(final byte[] bytes) throws DecoderException {
  186.         if (bytes == null) {
  187.             return null;
  188.         }
  189.         boolean hasUnderscores = false;
  190.         for (final byte b : bytes) {
  191.             if (b == UNDERSCORE) {
  192.                 hasUnderscores = true;
  193.                 break;
  194.             }
  195.         }
  196.         if (hasUnderscores) {
  197.             final byte[] tmp = new byte[bytes.length];
  198.             for (int i = 0; i < bytes.length; i++) {
  199.                 final byte b = bytes[i];
  200.                 if (b != UNDERSCORE) {
  201.                     tmp[i] = b;
  202.                 } else {
  203.                     tmp[i] = SPACE;
  204.                 }
  205.             }
  206.             return QuotedPrintableCodec.decodeQuotedPrintable(tmp);
  207.         }
  208.         return QuotedPrintableCodec.decodeQuotedPrintable(bytes);
  209.     }

  211.     @Override
  212.     protected byte[] doEncoding(final byte[] bytes) {
  213.         if (bytes == null) {
  214.             return null;
  215.         }
  216.         final byte[] data = QuotedPrintableCodec.encodeQuotedPrintable(PRINTABLE_CHARS, bytes);
  217.         if (this.encodeBlanks) {
  218.             for (int i = 0; i < data.length; i++) {
  219.                 if (data[i] == SPACE) {
  220.                     data[i] = UNDERSCORE;
  221.                 }
  222.             }
  223.         }
  224.         return data;
  225.     }

  227.     /**
  228.      * Encodes an object into its quoted-printable form using the default Charset. Unsafe characters are escaped.
  229.      *
  230.      * @param obj
  231.      *            object to convert to quoted-printable form
  232.      * @return quoted-printable object
  233.      * @throws EncoderException
  234.      *             thrown if a failure condition is encountered during the encoding process.
  235.      */
  236.     @Override
  237.     public Object encode(final Object obj) throws EncoderException {
  238.         if (obj == null) {
  239.             return null;
  240.         }
  241.         if (obj instanceof String) {
  242.             return encode((String) obj);
  243.         }
  244.         throw new EncoderException("Objects of type " + obj.getClass().getName() + " cannot be encoded using Q codec");
  245.     }

  247.     /**
  248.      * Encodes a string into its quoted-printable form using the default Charset. Unsafe characters are escaped.
  249.      *
  250.      * @param sourceStr
  251.      *            string to convert to quoted-printable form
  252.      * @return quoted-printable string
  253.      * @throws EncoderException
  254.      *             thrown if a failure condition is encountered during the encoding process.
  255.      */
  256.     @Override
  257.     public String encode(final String sourceStr) throws EncoderException {
  258.         return encode(sourceStr, getCharset());
  259.     }

  261.     /**
  262.      * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped.
  263.      *
  264.      * @param sourceStr
  265.      *            string to convert to quoted-printable form
  266.      * @param sourceCharset
  267.      *            the Charset for sourceStr
  268.      * @return quoted-printable string
  269.      * @throws EncoderException
  270.      *             thrown if a failure condition is encountered during the encoding process.
  271.      * @since 1.7
  272.      */
  273.     public String encode(final String sourceStr, final Charset sourceCharset) throws EncoderException {
  274.         return encodeText(sourceStr, sourceCharset);
  275.     }

  277.     /**
  278.      * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped.
  279.      *
  280.      * @param sourceStr
  281.      *            string to convert to quoted-printable form
  282.      * @param sourceCharset
  283.      *            the Charset for sourceStr
  284.      * @return quoted-printable string
  285.      * @throws EncoderException
  286.      *             thrown if a failure condition is encountered during the encoding process.
  287.      */
  288.     public String encode(final String sourceStr, final String sourceCharset) throws EncoderException {
  289.         try {
  290.             return encodeText(sourceStr, sourceCharset);
  291.         } catch (final UnsupportedCharsetException e) {
  292.             throw new EncoderException(e.getMessage(), e);
  293.         }
  294.     }

  296.     @Override
  297.     protected String getEncoding() {
  298.         return "Q";
  299.     }

  301.     /**
  302.      * Tests if optional transformation of SPACE characters is to be used
  303.      *
  304.      * @return {@code true} if SPACE characters are to be transformed, {@code false} otherwise
  305.      */
  306.     public boolean isEncodeBlanks() {
  307.         return this.encodeBlanks;
  308.     }

  310.     /**
  311.      * Defines whether optional transformation of SPACE characters is to be used
  312.      *
  313.      * @param b
  314.      *            {@code true} if SPACE characters are to be transformed, {@code false} otherwise
  315.      */
  316.     public void setEncodeBlanks(final boolean b) {
  317.         this.encodeBlanks = b;
  318.     }
  319. }
Created with JaCoCo 0.8.12.202403310830