QCodec


1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */ 
16  
17  package org.apache.commons.codec.net;
18  
19  import java.io.UnsupportedEncodingException  ;
20  import java.util.BitSet  ;
21  
22  import org.apache.commons.codec.DecoderException;
23  import org.apache.commons.codec.EncoderException;
24  import org.apache.commons.codec.StringDecoder;
25  import org.apache.commons.codec.StringEncoder;
26  
27  /**
28   * <p>
29   * Similar to the Quoted-Printable content-transfer-encoding defined in <a
30   * HREF="http://www.ietf.org/rfc/rfc1521.txt">RFC 1521</a> and designed to allow text containing mostly ASCII
31   * characters to be decipherable on an ASCII terminal without decoding.
32   * </p>
33   * 
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   * 
40   * @see <a HREF="http://www.ietf.org/rfc/rfc1522.txt">MIME (Multipurpose Internet Mail Extensions) Part Two: Message
41   *          Header Extensions for Non-ASCII Text</a>
42   * 
43   * @author Apache Software Foundation
44   * @since 1.3
45   * @version $Id: QCodec.java,v 1.6 2004/05/24 00:24:32 ggregory Exp $
46   */
47  public class QCodec extends RFC1522Codec implements StringEncoder, StringDecoder {
48      /**
49       * The default charset used for string decoding and encoding.
50       */
51      private String   charset = StringEncodings.UTF8;
52  
53      /**
54       * BitSet of printable characters as defined in RFC 1522.
55       */
56      private static final BitSet   PRINTABLE_CHARS = new BitSet  (256);
57      // Static initializer for printable chars collection
58      static {
59          // alpha characters
60          PRINTABLE_CHARS.set(' ');
61          PRINTABLE_CHARS.set('!');
62          PRINTABLE_CHARS.set('"');
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          for (int i = '0'; i <= '9'; i++) {
77              PRINTABLE_CHARS.set(i);
78          }
79          PRINTABLE_CHARS.set(':');
80          PRINTABLE_CHARS.set(';');
81          PRINTABLE_CHARS.set('<');
82          PRINTABLE_CHARS.set('>');
83          PRINTABLE_CHARS.set('@');
84          for (int i = 'A'; i <= 'Z'; i++) {
85              PRINTABLE_CHARS.set(i);
86          }
87          PRINTABLE_CHARS.set('[');
88          PRINTABLE_CHARS.set('\\');
89          PRINTABLE_CHARS.set(']');
90          PRINTABLE_CHARS.set('^');
91          PRINTABLE_CHARS.set('`');
92          for (int i = 'a'; i <= 'z'; i++) {
93              PRINTABLE_CHARS.set(i);
94          }
95          PRINTABLE_CHARS.set('{');
96          PRINTABLE_CHARS.set('|');
97          PRINTABLE_CHARS.set('}');
98          PRINTABLE_CHARS.set('~');
99      }
100 
101     private static byte BLANK = 32;
102 
103     private static byte UNDERSCORE = 95;
104 
105     private boolean encodeBlanks = false;
106 
107     /**
108      * Default constructor.
109      */
110     public QCodec() {
111         super();
112     }
113 
114     /**
115      * Constructor which allows for the selection of a default charset
116      * 
117      * @param charset
118      *                  the default string charset to use.
119      * 
120      * @see <a HREF="http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc">JRE character
121      *          encoding names</a>
122      */
123     public QCodec(final String   charset) {
124         super();
125         this.charset = charset;
126     }
127 
128     protected String   getEncoding() {
129         return "Q";
130     }
131 
132     protected byte[] doEncoding(byte[] bytes) throws EncoderException {
133         if (bytes == null) {
134             return null;
135         }
136         byte[] data = QuotedPrintableCodec.encodeQuotedPrintable(PRINTABLE_CHARS, bytes);
137         if (this.encodeBlanks) {
138             for (int i = 0; i < data.length; i++) {
139                 if (data[i] == BLANK) {
140                     data[i] = UNDERSCORE;
141                 }
142             }
143         }
144         return data;
145     }
146 
147     protected byte[] doDecoding(byte[] bytes) throws DecoderException {
148         if (bytes == null) {
149             return null;
150         }
151         boolean hasUnderscores = false;
152         for (int i = 0; i < bytes.length; i++) {
153             if (bytes[i] == UNDERSCORE) {
154                 hasUnderscores = true;
155                 break;
156             }
157         }
158         if (hasUnderscores) {
159             byte[] tmp = new byte[bytes.length];
160             for (int i = 0; i < bytes.length; i++) {
161                 byte b = bytes[i];
162                 if (b != UNDERSCORE) {
163                     tmp[i] = b;
164                 } else {
165                     tmp[i] = BLANK;
166                 }
167             }
168             return QuotedPrintableCodec.decodeQuotedPrintable(tmp);
169         } 
170         return QuotedPrintableCodec.decodeQuotedPrintable(bytes);       
171     }
172 
173     /**
174      * Encodes a string into its quoted-printable form using the specified charset. Unsafe characters are escaped.
175      * 
176      * @param pString
177      *                  string to convert to quoted-printable form
178      * @param charset
179      *                  the charset for pString
180      * @return quoted-printable string
181      * 
182      * @throws EncoderException
183      *                  thrown if a failure condition is encountered during the encoding process.
184      */
185     public String   encode(final String   pString, final String   charset) throws EncoderException {
186         if (pString == null) {
187             return null;
188         }
189         try {
190             return encodeText(pString, charset);
191         } catch (UnsupportedEncodingException   e) {
192             throw new EncoderException(e.getMessage());
193         }
194     }
195 
196     /**
197      * Encodes a string into its quoted-printable form using the default charset. Unsafe characters are escaped.
198      * 
199      * @param pString
200      *                  string to convert to quoted-printable form
201      * @return quoted-printable string
202      * 
203      * @throws EncoderException
204      *                  thrown if a failure condition is encountered during the encoding process.
205      */
206     public String   encode(String   pString) throws EncoderException {
207         if (pString == null) {
208             return null;
209         }
210         return encode(pString, getDefaultCharset());
211     }
212 
213     /**
214      * Decodes a quoted-printable string into its original form. Escaped characters are converted back to their original
215      * representation.
216      * 
217      * @param pString
218      *                  quoted-printable string to convert into its original form
219      * 
220      * @return original string
221      * 
222      * @throws DecoderException
223      *                  A decoder exception is thrown if a failure condition is encountered during the decode process.
224      */
225     public String   decode(String   pString) throws DecoderException {
226         if (pString == null) {
227             return null;
228         }
229         try {
230             return decodeText(pString);
231         } catch (UnsupportedEncodingException   e) {
232             throw new DecoderException(e.getMessage());
233         }
234     }
235 
236     /**
237      * Encodes an object into its quoted-printable form using the default charset. Unsafe characters are escaped.
238      * 
239      * @param pObject
240      *                  object to convert to quoted-printable form
241      * @return quoted-printable object
242      * 
243      * @throws EncoderException
244      *                  thrown if a failure condition is encountered during the encoding process.
245      */
246     public Object   encode(Object   pObject) throws EncoderException {
247         if (pObject == null) {
248             return null;
249         } else if (pObject instanceof String  ) {
250             return encode((String  ) pObject);
251         } else {
252             throw new EncoderException("Objects of type "
253                 + pObject.getClass().getName()
254                 + " cannot be encoded using Q codec");
255         }
256     }
257 
258     /**
259      * Decodes a quoted-printable object into its original form. Escaped characters are converted back to their original
260      * representation.
261      * 
262      * @param pObject
263      *                  quoted-printable object to convert into its original form
264      * 
265      * @return original object
266      * 
267      * @throws DecoderException
268      *                  A decoder exception is thrown if a failure condition is encountered during the decode process.
269      */
270     public Object   decode(Object   pObject) throws DecoderException {
271         if (pObject == null) {
272             return null;
273         } else if (pObject instanceof String  ) {
274             return decode((String  ) pObject);
275         } else {
276             throw new DecoderException("Objects of type "
277                 + pObject.getClass().getName()
278                 + " cannot be decoded using Q codec");
279         }
280     }
281 
282     /**
283      * The default charset used for string decoding and encoding.
284      * 
285      * @return the default string charset.
286      */
287     public String   getDefaultCharset() {
288         return this.charset;
289     }
290 
291     /**
292      * Tests if optional tranformation of SPACE characters is to be used
293      * 
294      * @return <code>true</code> if SPACE characters are to be transformed, <code>false</code> otherwise
295      */
296     public boolean isEncodeBlanks() {
297         return this.encodeBlanks;
298     }
299 
300     /**
301      * Defines whether optional tranformation of SPACE characters is to be used
302      * 
303      * @param b
304      *                  <code>true</code> if SPACE characters are to be transformed, <code>false</code> otherwise
305      */
306     public void setEncodeBlanks(boolean b) {
307         this.encodeBlanks = b;
308     }
309 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags