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
17package org.apache.commons.codec.net;
18
19import java.io.UnsupportedEncodingException;
20import org.apache.commons.codec.DecoderException;
21import org.apache.commons.codec.EncoderException;
22import org.apache.commons.codec.StringDecoder;
23import org.apache.commons.codec.StringEncoder;
24import 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
50public 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     */
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     */
72    public BCodec(final String charset) {
73        super();
74        this.charset = charset;
75    }
76
77    protected String getEncoding() {
78        return "B";
79    }
80
81    protected byte[] doEncoding(byte[] bytes) throws EncoderException {
82        if (bytes == null) {
83            return null;
84        }
85        return Base64.encodeBase64(bytes);
86    }
87
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     */
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     */
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     */
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     */
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     */
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     */
209    public String getDefaultCharset() {
210        return this.charset;
211    }
212}
213