1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.codec.net;
19
20 import java.io.UnsupportedEncodingException;
21
22 import org.apache.commons.codec.CharEncoding;
23 import org.apache.commons.codec.DecoderException;
24 import org.apache.commons.codec.EncoderException;
25 import org.apache.commons.codec.StringDecoder;
26 import org.apache.commons.codec.StringEncoder;
27 import org.apache.commons.codec.binary.Base64;
28
29 /**
30 * <p>
31 * Identical to the Base64 encoding defined by <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC
32 * 1521</a> and allows a character set to be specified.
33 * </p>
34 *
35 * <p>
36 * <a href="http://www.ietf.org/rfc/rfc1522.txt">RFC 1522</a> describes techniques to allow the encoding of non-ASCII
37 * text in various portions of a RFC 822 [2] message header, in a manner which is unlikely to confuse existing message
38 * handling software.
39 * </p>
40 *
41 * @see <a href="http://www.ietf.org/rfc/rfc1522.txt">MIME (Multipurpose Internet Mail Extensions) Part Two: Message
42 * Header Extensions for Non-ASCII Text</a>
43 *
44 * @author Apache Software Foundation
45 * @since 1.3
46 * @version $Id: BCodec.java 1157192 2011-08-12 17:27:38Z ggregory $
47 */
48 public class BCodec extends RFC1522Codec implements StringEncoder, StringDecoder {
49 /**
50 * The default charset used for string decoding and encoding.
51 */
52 private final String charset;
53
54 /**
55 * Default constructor.
56 */
57 public BCodec() {
58 this(CharEncoding.UTF_8);
59 }
60
61 /**
62 * Constructor which allows for the selection of a default charset
63 *
64 * @param charset
65 * the default string charset to use.
66 *
67 * @see <a href="http://download.oracle.com/javase/1.5.0/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
68 */
69 public BCodec(final String charset) {
70 super();
71 this.charset = charset;
72 }
73
74 @Override
75 protected String getEncoding() {
76 return "B";
77 }
78
79 @Override
80 protected byte[] doEncoding(byte[] bytes) {
81 if (bytes == null) {
82 return null;
83 }
84 return Base64.encodeBase64(bytes);
85 }
86
87 @Override
88 protected byte[] doDecoding(byte[] bytes) {
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 <code>value</code>
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(), e);
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 * @return original string
142 * @throws DecoderException
143 * A decoder exception is thrown if a failure condition is encountered during the decode process.
144 */
145 public String decode(String value) throws DecoderException {
146 if (value == null) {
147 return null;
148 }
149 try {
150 return decodeText(value);
151 } catch (UnsupportedEncodingException e) {
152 throw new DecoderException(e.getMessage(), e);
153 }
154 }
155
156 /**
157 * Encodes an object into its Base64 form using the default charset. Unsafe characters are escaped.
158 *
159 * @param value
160 * object to convert to Base64 form
161 * @return Base64 object
162 *
163 * @throws EncoderException
164 * thrown if a failure condition is encountered during the encoding process.
165 */
166 public Object encode(Object value) throws EncoderException {
167 if (value == null) {
168 return null;
169 } else if (value instanceof String) {
170 return encode((String) value);
171 } else {
172 throw new EncoderException("Objects of type " +
173 value.getClass().getName() +
174 " cannot be encoded using BCodec");
175 }
176 }
177
178 /**
179 * Decodes a Base64 object into its original form. Escaped characters are converted back to their original
180 * representation.
181 *
182 * @param value
183 * Base64 object to convert into its original form
184 *
185 * @return original object
186 *
187 * @throws DecoderException
188 * Thrown if the argument is not a <code>String</code>. Thrown if a failure condition is
189 * encountered during the decode process.
190 */
191 public Object decode(Object value) throws DecoderException {
192 if (value == null) {
193 return null;
194 } else if (value instanceof String) {
195 return decode((String) value);
196 } else {
197 throw new DecoderException("Objects of type " +
198 value.getClass().getName() +
199 " cannot be decoded using BCodec");
200 }
201 }
202
203 /**
204 * The default charset used for string decoding and encoding.
205 *
206 * @return the default string charset.
207 */
208 public String getDefaultCharset() {
209 return this.charset;
210 }
211 }