001: /*
002: * Copyright 2001-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.codec.net;
018:
019: import java.io.UnsupportedEncodingException;
020: import org.apache.commons.codec.DecoderException;
021: import org.apache.commons.codec.EncoderException;
022: import org.apache.commons.codec.StringDecoder;
023: import org.apache.commons.codec.StringEncoder;
024: import org.apache.commons.codec.binary.Base64;
025:
026: /**
027: * <p>
028: * Identical to the Base64 encoding defined by <a href="http://www.ietf.org/rfc/rfc1521.txt">RFC
029: * 1521</a> and allows a character set to be specified.
030: * </p>
031: *
032: * <p>
033: * <a href="http://www.ietf.org/rfc/rfc1522.txt">RFC 1522</a> describes techniques to allow the encoding of non-ASCII
034: * text in various portions of a RFC 822 [2] message header, in a manner which is unlikely to confuse existing message
035: * handling software.
036: * </p>
037: *
038: * @see <a href="http://www.ietf.org/rfc/rfc1522.txt">MIME (Multipurpose Internet Mail Extensions) Part Two: Message
039: * Header Extensions for Non-ASCII Text</a>
040: *
041: * @author Apache Software Foundation
042: * @since 1.3
043: * @version $Id: BCodec.java,v 1.5 2004/04/13 22:46:37 ggregory Exp $
044: */
045: public class BCodec extends RFC1522Codec implements StringEncoder,
046: StringDecoder {
047: /**
048: * The default charset used for string decoding and encoding.
049: */
050: private String charset = StringEncodings.UTF8;
051:
052: /**
053: * Default constructor.
054: */
055: public BCodec() {
056: super ();
057: }
058:
059: /**
060: * Constructor which allows for the selection of a default charset
061: *
062: * @param charset
063: * the default string charset to use.
064: *
065: * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/package-summary.html#charenc">JRE character
066: * encoding names</a>
067: */
068: public BCodec(final String charset) {
069: super ();
070: this .charset = charset;
071: }
072:
073: protected String getEncoding() {
074: return "B";
075: }
076:
077: protected byte[] doEncoding(byte[] bytes) throws EncoderException {
078: if (bytes == null) {
079: return null;
080: }
081: return Base64.encodeBase64(bytes);
082: }
083:
084: protected byte[] doDecoding(byte[] bytes) throws DecoderException {
085: if (bytes == null) {
086: return null;
087: }
088: return Base64.decodeBase64(bytes);
089: }
090:
091: /**
092: * Encodes a string into its Base64 form using the specified charset. Unsafe characters are escaped.
093: *
094: * @param value
095: * string to convert to Base64 form
096: * @param charset
097: * the charset for pString
098: * @return Base64 string
099: *
100: * @throws EncoderException
101: * thrown if a failure condition is encountered during the encoding process.
102: */
103: public String encode(final String value, final String charset)
104: throws EncoderException {
105: if (value == null) {
106: return null;
107: }
108: try {
109: return encodeText(value, charset);
110: } catch (UnsupportedEncodingException e) {
111: throw new EncoderException(e.getMessage());
112: }
113: }
114:
115: /**
116: * Encodes a string into its Base64 form using the default charset. Unsafe characters are escaped.
117: *
118: * @param value
119: * string to convert to Base64 form
120: * @return Base64 string
121: *
122: * @throws EncoderException
123: * thrown if a failure condition is encountered during the encoding process.
124: */
125: public String encode(String value) throws EncoderException {
126: if (value == null) {
127: return null;
128: }
129: return encode(value, getDefaultCharset());
130: }
131:
132: /**
133: * Decodes a Base64 string into its original form. Escaped characters are converted back to their original
134: * representation.
135: *
136: * @param value
137: * Base64 string to convert into its original form
138: *
139: * @return original string
140: *
141: * @throws DecoderException
142: * A decoder exception is thrown if a failure condition is encountered during the decode process.
143: */
144: public String decode(String value) throws DecoderException {
145: if (value == null) {
146: return null;
147: }
148: try {
149: return decodeText(value);
150: } catch (UnsupportedEncodingException e) {
151: throw new DecoderException(e.getMessage());
152: }
153: }
154:
155: /**
156: * Encodes an object into its Base64 form using the default charset. Unsafe characters are escaped.
157: *
158: * @param value
159: * object to convert to Base64 form
160: * @return Base64 object
161: *
162: * @throws EncoderException
163: * thrown if a failure condition is encountered during the encoding process.
164: */
165: public Object encode(Object value) throws EncoderException {
166: if (value == null) {
167: return null;
168: } else if (value instanceof String) {
169: return encode((String) value);
170: } else {
171: throw new EncoderException("Objects of type "
172: + value.getClass().getName()
173: + " cannot be encoded using BCodec");
174: }
175: }
176:
177: /**
178: * Decodes a Base64 object into its original form. Escaped characters are converted back to their original
179: * representation.
180: *
181: * @param value
182: * Base64 object to convert into its original form
183: *
184: * @return original object
185: *
186: * @throws DecoderException
187: * A decoder exception is thrown if a failure condition is encountered during the decode process.
188: */
189: public Object decode(Object value) throws DecoderException {
190: if (value == null) {
191: return null;
192: } else if (value instanceof String) {
193: return decode((String) value);
194: } else {
195: throw new DecoderException("Objects of type "
196: + value.getClass().getName()
197: + " cannot be decoded using BCodec");
198: }
199: }
200:
201: /**
202: * The default charset used for string decoding and encoding.
203: *
204: * @return the default string charset.
205: */
206: public String getDefaultCharset() {
207: return this.charset;
208: }
209: }
|