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 <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 127 * @since 1.7 128 */ 129 public QCodec(final Charset charset) { 130 super(); 131 this.charset = charset; 132 } 133 134 /** 135 * Constructor which allows for the selection of a default Charset. 136 * 137 * @param charsetName 138 * the Charset to use. 139 * @throws java.nio.charset.UnsupportedCharsetException 140 * If the named Charset is unavailable 141 * @since 1.7 throws UnsupportedCharsetException if the named Charset is unavailable 142 * @see <a href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 143 */ 144 public QCodec(final String charsetName) { 145 this(Charset.forName(charsetName)); 146 } 147 148 @Override 149 protected String getEncoding() { 150 return "Q"; 151 } 152 153 @Override 154 protected byte[] doEncoding(final byte[] bytes) { 155 if (bytes == null) { 156 return null; 157 } 158 final byte[] data = QuotedPrintableCodec.encodeQuotedPrintable(PRINTABLE_CHARS, bytes); 159 if (this.encodeBlanks) { 160 for (int i = 0; i < data.length; i++) { 161 if (data[i] == SPACE) { 162 data[i] = UNDERSCORE; 163 } 164 } 165 } 166 return data; 167 } 168 169 @Override 170 protected byte[] doDecoding(final byte[] bytes) throws DecoderException { 171 if (bytes == null) { 172 return null; 173 } 174 boolean hasUnderscores = false; 175 for (final byte b : bytes) { 176 if (b == UNDERSCORE) { 177 hasUnderscores = true; 178 break; 179 } 180 } 181 if (hasUnderscores) { 182 final byte[] tmp = new byte[bytes.length]; 183 for (int i = 0; i < bytes.length; i++) { 184 final byte b = bytes[i]; 185 if (b != UNDERSCORE) { 186 tmp[i] = b; 187 } else { 188 tmp[i] = SPACE; 189 } 190 } 191 return QuotedPrintableCodec.decodeQuotedPrintable(tmp); 192 } 193 return QuotedPrintableCodec.decodeQuotedPrintable(bytes); 194 } 195 196 /** 197 * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. 198 * 199 * @param sourceStr 200 * string to convert to quoted-printable form 201 * @param sourceCharset 202 * the Charset for sourceStr 203 * @return quoted-printable string 204 * @throws EncoderException 205 * thrown if a failure condition is encountered during the encoding process. 206 * @since 1.7 207 */ 208 public String encode(final String sourceStr, final Charset sourceCharset) throws EncoderException { 209 if (sourceStr == null) { 210 return null; 211 } 212 return encodeText(sourceStr, sourceCharset); 213 } 214 215 /** 216 * Encodes a string into its quoted-printable form using the specified Charset. Unsafe characters are escaped. 217 * 218 * @param sourceStr 219 * string to convert to quoted-printable form 220 * @param sourceCharset 221 * the Charset for sourceStr 222 * @return quoted-printable string 223 * @throws EncoderException 224 * thrown if a failure condition is encountered during the encoding process. 225 */ 226 public String encode(final String sourceStr, final String sourceCharset) throws EncoderException { 227 if (sourceStr == null) { 228 return null; 229 } 230 try { 231 return encodeText(sourceStr, sourceCharset); 232 } catch (final UnsupportedEncodingException e) { 233 throw new EncoderException(e.getMessage(), e); 234 } 235 } 236 237 /** 238 * Encodes a string into its quoted-printable form using the default Charset. Unsafe characters are escaped. 239 * 240 * @param sourceStr 241 * string to convert to quoted-printable form 242 * @return quoted-printable string 243 * @throws EncoderException 244 * thrown if a failure condition is encountered during the encoding process. 245 */ 246 @Override 247 public String encode(final String sourceStr) throws EncoderException { 248 if (sourceStr == null) { 249 return null; 250 } 251 return encode(sourceStr, getCharset()); 252 } 253 254 /** 255 * Decodes a quoted-printable string into its original form. Escaped characters are converted back to their original 256 * representation. 257 * 258 * @param str 259 * quoted-printable string to convert into its original form 260 * @return original string 261 * @throws DecoderException 262 * A decoder exception is thrown if a failure condition is encountered during the decode process. 263 */ 264 @Override 265 public String decode(final String str) throws DecoderException { 266 if (str == null) { 267 return null; 268 } 269 try { 270 return decodeText(str); 271 } catch (final UnsupportedEncodingException e) { 272 throw new DecoderException(e.getMessage(), e); 273 } 274 } 275 276 /** 277 * Encodes an object into its quoted-printable form using the default Charset. Unsafe characters are escaped. 278 * 279 * @param obj 280 * object to convert to quoted-printable form 281 * @return quoted-printable object 282 * @throws EncoderException 283 * thrown if a failure condition is encountered during the encoding process. 284 */ 285 @Override 286 public Object encode(final Object obj) throws EncoderException { 287 if (obj == null) { 288 return null; 289 } else if (obj instanceof String) { 290 return encode((String) obj); 291 } else { 292 throw new EncoderException("Objects of type " + 293 obj.getClass().getName() + 294 " cannot be encoded using Q codec"); 295 } 296 } 297 298 /** 299 * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original 300 * representation. 301 * 302 * @param obj 303 * quoted-printable object to convert into its original form 304 * @return original object 305 * @throws DecoderException 306 * Thrown if the argument is not a {@code String}. Thrown if a failure condition is encountered 307 * during the decode process. 308 */ 309 @Override 310 public Object decode(final Object obj) throws DecoderException { 311 if (obj == null) { 312 return null; 313 } else if (obj instanceof String) { 314 return decode((String) obj); 315 } else { 316 throw new DecoderException("Objects of type " + 317 obj.getClass().getName() + 318 " cannot be decoded using Q codec"); 319 } 320 } 321 322 /** 323 * Gets the default Charset name used for string decoding and encoding. 324 * 325 * @return the default Charset name 326 * @since 1.7 327 */ 328 public Charset getCharset() { 329 return this.charset; 330 } 331 332 /** 333 * Gets the default Charset name used for string decoding and encoding. 334 * 335 * @return the default Charset name 336 */ 337 public String getDefaultCharset() { 338 return this.charset.name(); 339 } 340 341 /** 342 * Tests if optional transformation of SPACE characters is to be used 343 * 344 * @return {@code true} if SPACE characters are to be transformed, {@code false} otherwise 345 */ 346 public boolean isEncodeBlanks() { 347 return this.encodeBlanks; 348 } 349 350 /** 351 * Defines whether optional transformation of SPACE characters is to be used 352 * 353 * @param b 354 * {@code true} if SPACE characters are to be transformed, {@code false} otherwise 355 */ 356 public void setEncodeBlanks(final boolean b) { 357 this.encodeBlanks = b; 358 } 359}