001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.codec.net; 019 020import java.io.UnsupportedEncodingException; 021import java.nio.charset.Charset; 022import java.nio.charset.StandardCharsets; 023import java.util.BitSet; 024 025import org.apache.commons.codec.DecoderException; 026import org.apache.commons.codec.EncoderException; 027import org.apache.commons.codec.StringDecoder; 028import org.apache.commons.codec.StringEncoder; 029 030/** 031 * Similar to the Quoted-Printable content-transfer-encoding defined in 032 * <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a> and designed to allow text containing mostly ASCII 033 * characters to be decipherable on an ASCII terminal without decoding. 034 * <p> 035 * <a href="http://www.ietf.org/rfc/rfc1522.txt">RFC 1522</a> describes techniques to allow the encoding of non-ASCII 036 * text in various portions of a RFC 822 [2] message header, in a manner which is unlikely to confuse existing message 037 * handling software. 038 * </p> 039 * <p> 040 * This class is conditionally thread-safe. 041 * The instance field for encoding blanks is mutable {@link #setEncodeBlanks(boolean)} 042 * but is not volatile, and accesses are not synchronised. 043 * If an instance of the class is shared between threads, the caller needs to ensure that suitable synchronisation 044 * is used to ensure safe publication of the value between threads, and must not invoke 045 * {@link #setEncodeBlanks(boolean)} after initial setup. 046 * </p> 047 * 048 * @see <a href="http://www.ietf.org/rfc/rfc1522.txt">MIME (Multipurpose Internet Mail Extensions) Part Two: Message 049 * Header Extensions for Non-ASCII Text</a> 050 * 051 * @since 1.3 052 */ 053public class QCodec extends RFC1522Codec implements StringEncoder, StringDecoder { 054 /** 055 * The default Charset used for string decoding and encoding. 056 */ 057 private final Charset charset; 058 059 /** 060 * BitSet of printable characters as defined in RFC 1522. 061 */ 062 private static final BitSet PRINTABLE_CHARS = new BitSet(256); 063 // Static initializer for printable chars collection 064 static { 065 // alpha characters 066 PRINTABLE_CHARS.set(' '); 067 PRINTABLE_CHARS.set('!'); 068 PRINTABLE_CHARS.set('"'); 069 PRINTABLE_CHARS.set('#'); 070 PRINTABLE_CHARS.set('$'); 071 PRINTABLE_CHARS.set('%'); 072 PRINTABLE_CHARS.set('&'); 073 PRINTABLE_CHARS.set('\''); 074 PRINTABLE_CHARS.set('('); 075 PRINTABLE_CHARS.set(')'); 076 PRINTABLE_CHARS.set('*'); 077 PRINTABLE_CHARS.set('+'); 078 PRINTABLE_CHARS.set(','); 079 PRINTABLE_CHARS.set('-'); 080 PRINTABLE_CHARS.set('.'); 081 PRINTABLE_CHARS.set('/'); 082 for (int i = '0'; i <= '9'; i++) { 083 PRINTABLE_CHARS.set(i); 084 } 085 PRINTABLE_CHARS.set(':'); 086 PRINTABLE_CHARS.set(';'); 087 PRINTABLE_CHARS.set('<'); 088 PRINTABLE_CHARS.set('>'); 089 PRINTABLE_CHARS.set('@'); 090 for (int i = 'A'; i <= 'Z'; i++) { 091 PRINTABLE_CHARS.set(i); 092 } 093 PRINTABLE_CHARS.set('['); 094 PRINTABLE_CHARS.set('\\'); 095 PRINTABLE_CHARS.set(']'); 096 PRINTABLE_CHARS.set('^'); 097 PRINTABLE_CHARS.set('`'); 098 for (int i = 'a'; i <= 'z'; i++) { 099 PRINTABLE_CHARS.set(i); 100 } 101 PRINTABLE_CHARS.set('{'); 102 PRINTABLE_CHARS.set('|'); 103 PRINTABLE_CHARS.set('}'); 104 PRINTABLE_CHARS.set('~'); 105 } 106 107 private static final byte SPACE = 32; 108 109 private static final byte UNDERSCORE = 95; 110 111 private boolean encodeBlanks = false; 112 113 /** 114 * Default constructor. 115 */ 116 public QCodec() { 117 this(StandardCharsets.UTF_8); 118 } 119 120 /** 121 * Constructor which allows for the selection of a default Charset. 122 * 123 * @param charset 124 * the default string Charset to use. 125 * 126 * @see Charset 127 * @since 1.7 128 */ 129 public QCodec(final Charset charset) { 130 this.charset = charset; 131 } 132 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 Charset 142 */ 143 public QCodec(final String charsetName) { 144 this(Charset.forName(charsetName)); 145 } 146 147 @Override 148 protected String getEncoding() { 149 return "Q"; 150 } 151 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] == SPACE) { 161 data[i] = UNDERSCORE; 162 } 163 } 164 } 165 return data; 166 } 167 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] = SPACE; 188 } 189 } 190 return QuotedPrintableCodec.decodeQuotedPrintable(tmp); 191 } 192 return QuotedPrintableCodec.decodeQuotedPrintable(bytes); 193 } 194 195 /** 196 * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. 197 * 198 * @param sourceStr 199 * string to convert to quoted-printable form 200 * @param sourceCharset 201 * the Charset for sourceStr 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 sourceStr, final Charset sourceCharset) throws EncoderException { 208 if (sourceStr == null) { 209 return null; 210 } 211 return encodeText(sourceStr, sourceCharset); 212 } 213 214 /** 215 * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. 216 * 217 * @param sourceStr 218 * string to convert to quoted-printable form 219 * @param sourceCharset 220 * the Charset for sourceStr 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 sourceStr, final String sourceCharset) throws EncoderException { 226 if (sourceStr == null) { 227 return null; 228 } 229 try { 230 return encodeText(sourceStr, sourceCharset); 231 } catch (final UnsupportedEncodingException e) { 232 throw new EncoderException(e.getMessage(), e); 233 } 234 } 235 236 /** 237 * Encodes a string into its quoted-printable form using the default Charset. Unsafe characters are escaped. 238 * 239 * @param sourceStr 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 sourceStr) throws EncoderException { 247 if (sourceStr == null) { 248 return null; 249 } 250 return encode(sourceStr, getCharset()); 251 } 252 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 } 274 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 } 289 if (obj instanceof String) { 290 return encode((String) obj); 291 } 292 throw new EncoderException("Objects of type " + 293 obj.getClass().getName() + 294 " cannot be encoded using Q codec"); 295 } 296 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}. 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 } 313 if (obj instanceof String) { 314 return decode((String) obj); 315 } 316 throw new DecoderException("Objects of type " + 317 obj.getClass().getName() + 318 " cannot be decoded using Q codec"); 319 } 320 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 } 330 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 } 339 340 /** 341 * Tests if optional transformation of SPACE characters is to be used 342 * 343 * @return {@code true} if SPACE characters are to be transformed, {@code false} otherwise 344 */ 345 public boolean isEncodeBlanks() { 346 return this.encodeBlanks; 347 } 348 349 /** 350 * Defines whether optional transformation of SPACE characters is to be used 351 * 352 * @param b 353 * {@code true} if SPACE characters are to be transformed, {@code false} otherwise 354 */ 355 public void setEncodeBlanks(final boolean b) { 356 this.encodeBlanks = b; 357 } 358}