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 org.apache.commons.codec.DecoderException;
21 import org.apache.commons.codec.EncoderException;
22 import org.apache.commons.codec.StringDecoder;
23 import org.apache.commons.codec.StringEncoder;
24 import org.apache.commons.codec.binary.Base64;
25 
26 /**
27  * <p>
28  * Identical to the Base64 encoding defined by <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC
29  * 1521</a> and allows a character set to be specified.
30  * </p>
31  *
32  * <p>
33  * <a href="http://www.ietf.org/rfc/rfc1522.txt">RFC 1522</a> describes techniques to allow the encoding of non-ASCII
34  * text in various portions of a RFC 822 [2] message header, in a manner which is unlikely to confuse existing message
35  * handling software.
36  * </p>
37  *
38  * @see <a href="http://www.ietf.org/rfc/rfc1522.txt">MIME (Multipurpose Internet Mail Extensions) Part Two: Message
39  *          Header Extensions for Non-ASCII Text</a>
40  *
41  * @author Apache Software Foundation
42  * @since 1.3
43  * @version $Id: BCodec.java,v 1.5 2004/04/13 22:46:37 ggregory Exp $
44  *
45  * @deprecated Please use {@link java.net.URL#openConnection} instead.
46  *     Please visit <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html">this webpage</a>
47  *     for further details.
48  */
49 @Deprecated
50 public class BCodec extends RFC1522Codec implements StringEncoder, StringDecoder {
51     /**
52      * The default charset used for string decoding and encoding.
53      */
54     private String charset = StringEncodings.UTF8;
55 
56     /**
57      * Default constructor.
58      */
BCodec()59     public BCodec() {
60         super();
61     }
62 
63     /**
64      * Constructor which allows for the selection of a default charset
65      *
66      * @param charset
67      *                  the default string charset to use.
68      *
69      * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc">JRE character
70      *          encoding names</a>
71      */
BCodec(final String charset)72     public BCodec(final String charset) {
73         super();
74         this.charset = charset;
75     }
76 
getEncoding()77     protected String getEncoding() {
78         return "B";
79     }
80 
doEncoding(byte[] bytes)81     protected byte[] doEncoding(byte[] bytes) throws EncoderException {
82         if (bytes == null) {
83             return null;
84         }
85         return Base64.encodeBase64(bytes);
86     }
87 
doDecoding(byte[] bytes)88     protected byte[] doDecoding(byte[] bytes) throws DecoderException {
89         if (bytes == null) {
90             return null;
91         }
92         return Base64.decodeBase64(bytes);
93     }
94 
95     /**
96      * Encodes a string into its Base64 form using the specified charset. Unsafe characters are escaped.
97      *
98      * @param value
99      *                  string to convert to Base64 form
100      * @param charset
101      *                  the charset for pString
102      * @return Base64 string
103      *
104      * @throws EncoderException
105      *                  thrown if a failure condition is encountered during the encoding process.
106      */
encode(final String value, final String charset)107     public String encode(final String value, final String charset) throws EncoderException {
108         if (value == null) {
109             return null;
110         }
111         try {
112             return encodeText(value, charset);
113         } catch (UnsupportedEncodingException e) {
114             throw new EncoderException(e.getMessage());
115         }
116     }
117 
118     /**
119      * Encodes a string into its Base64 form using the default charset. Unsafe characters are escaped.
120      *
121      * @param value
122      *                  string to convert to Base64 form
123      * @return Base64 string
124      *
125      * @throws EncoderException
126      *                  thrown if a failure condition is encountered during the encoding process.
127      */
encode(String value)128     public String encode(String value) throws EncoderException {
129         if (value == null) {
130             return null;
131         }
132         return encode(value, getDefaultCharset());
133     }
134 
135     /**
136      * Decodes a Base64 string into its original form. Escaped characters are converted back to their original
137      * representation.
138      *
139      * @param value
140      *                  Base64 string to convert into its original form
141      *
142      * @return original string
143      *
144      * @throws DecoderException
145      *                  A decoder exception is thrown if a failure condition is encountered during the decode process.
146      */
decode(String value)147     public String decode(String value) throws DecoderException {
148         if (value == null) {
149             return null;
150         }
151         try {
152             return decodeText(value);
153         } catch (UnsupportedEncodingException e) {
154             throw new DecoderException(e.getMessage());
155         }
156     }
157 
158     /**
159      * Encodes an object into its Base64 form using the default charset. Unsafe characters are escaped.
160      *
161      * @param value
162      *                  object to convert to Base64 form
163      * @return Base64 object
164      *
165      * @throws EncoderException
166      *                  thrown if a failure condition is encountered during the encoding process.
167      */
encode(Object value)168     public Object encode(Object value) throws EncoderException {
169         if (value == null) {
170             return null;
171         } else if (value instanceof String) {
172             return encode((String) value);
173         } else {
174             throw new EncoderException("Objects of type "
175                 + value.getClass().getName()
176                 + " cannot be encoded using BCodec");
177         }
178     }
179 
180     /**
181      * Decodes a Base64 object into its original form. Escaped characters are converted back to their original
182      * representation.
183      *
184      * @param value
185      *                  Base64 object to convert into its original form
186      *
187      * @return original object
188      *
189      * @throws DecoderException
190      *                  A decoder exception is thrown if a failure condition is encountered during the decode process.
191      */
decode(Object value)192     public Object decode(Object value) throws DecoderException {
193         if (value == null) {
194             return null;
195         } else if (value instanceof String) {
196             return decode((String) value);
197         } else {
198             throw new DecoderException("Objects of type "
199                 + value.getClass().getName()
200                 + " cannot be decoded using BCodec");
201         }
202     }
203 
204     /**
205      * The default charset used for string decoding and encoding.
206      *
207      * @return the default string charset.
208      */
getDefaultCharset()209     public String getDefaultCharset() {
210         return this.charset;
211     }
212 }
213