001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.codec.binary;
019
020 import java.io.FilterOutputStream;
021 import java.io.IOException;
022 import java.io.OutputStream;
023
024 /**
025 * Provides Base64 encoding and decoding in a streaming fashion (unlimited size). When encoding the default lineLength
026 * is 76 characters and the default lineEnding is CRLF, but these can be overridden by using the appropriate
027 * constructor.
028 * <p>
029 * The default behaviour of the Base64OutputStream is to ENCODE, whereas the default behaviour of the Base64InputStream
030 * is to DECODE. But this behaviour can be overridden by using a different constructor.
031 * </p>
032 * <p>
033 * This class implements section <cite>6.8. Base64 Content-Transfer-Encoding</cite> from RFC 2045 <cite>Multipurpose
034 * Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</cite> by Freed and Borenstein.
035 * </p>
036 * <p>
037 * Since this class operates directly on byte streams, and not character streams, it is hard-coded to only encode/decode
038 * character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252, UTF-8, etc).
039 * </p>
040 *
041 * @author Apache Software Foundation
042 * @version $Id: Base64OutputStream.java 799806 2009-08-01 04:33:17Z ggregory $
043 * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
044 * @since 1.4
045 */
046 public class Base64OutputStream extends FilterOutputStream {
047 private final boolean doEncode;
048
049 private final Base64 base64;
050
051 private final byte[] singleByte = new byte[1];
052
053 /**
054 * Creates a Base64OutputStream such that all data written is Base64-encoded to the original provided OutputStream.
055 *
056 * @param out
057 * OutputStream to wrap.
058 */
059 public Base64OutputStream(OutputStream out) {
060 this(out, true);
061 }
062
063 /**
064 * Creates a Base64OutputStream such that all data written is either Base64-encoded or Base64-decoded to the
065 * original provided OutputStream.
066 *
067 * @param out
068 * OutputStream to wrap.
069 * @param doEncode
070 * true if we should encode all data written to us, false if we should decode.
071 */
072 public Base64OutputStream(OutputStream out, boolean doEncode) {
073 super(out);
074 this.doEncode = doEncode;
075 this.base64 = new Base64();
076 }
077
078 /**
079 * Creates a Base64OutputStream such that all data written is either Base64-encoded or Base64-decoded to the
080 * original provided OutputStream.
081 *
082 * @param out
083 * OutputStream to wrap.
084 * @param doEncode
085 * true if we should encode all data written to us, false if we should decode.
086 * @param lineLength
087 * If doEncode is true, each line of encoded data will contain lineLength characters (rounded down to
088 * nearest multiple of 4). If lineLength <=0, the encoded data is not divided into lines. If doEncode is
089 * false, lineLength is ignored.
090 * @param lineSeparator
091 * If doEncode is true, each line of encoded data will be terminated with this byte sequence (e.g. \r\n).
092 * If lineLength <= 0, the lineSeparator is not used. If doEncode is false lineSeparator is ignored.
093 */
094 public Base64OutputStream(OutputStream out, boolean doEncode, int lineLength, byte[] lineSeparator) {
095 super(out);
096 this.doEncode = doEncode;
097 this.base64 = new Base64(lineLength, lineSeparator);
098 }
099
100 /**
101 * Writes the specified <code>byte</code> to this output stream.
102 *
103 * @param i
104 * source byte
105 * @throws IOException
106 * if an I/O error occurs.
107 */
108 public void write(int i) throws IOException {
109 singleByte[0] = (byte) i;
110 write(singleByte, 0, 1);
111 }
112
113 /**
114 * Writes <code>len</code> bytes from the specified <code>b</code> array starting at <code>offset</code> to this
115 * output stream.
116 *
117 * @param b
118 * source byte array
119 * @param offset
120 * where to start reading the bytes
121 * @param len
122 * maximum number of bytes to write
123 *
124 * @throws IOException
125 * if an I/O error occurs.
126 * @throws NullPointerException
127 * if the byte array parameter is null
128 * @throws IndexOutOfBoundsException
129 * if offset, len or buffer size are invalid
130 */
131 public void write(byte b[], int offset, int len) throws IOException {
132 if (b == null) {
133 throw new NullPointerException();
134 } else if (offset < 0 || len < 0) {
135 throw new IndexOutOfBoundsException();
136 } else if (offset > b.length || offset + len > b.length) {
137 throw new IndexOutOfBoundsException();
138 } else if (len > 0) {
139 if (doEncode) {
140 base64.encode(b, offset, len);
141 } else {
142 base64.decode(b, offset, len);
143 }
144 flush(false);
145 }
146 }
147
148 /**
149 * Flushes this output stream and forces any buffered output bytes to be written out to the stream. If propogate is
150 * true, the wrapped stream will also be flushed.
151 *
152 * @param propogate
153 * boolean flag to indicate whether the wrapped OutputStream should also be flushed.
154 * @throws IOException
155 * if an I/O error occurs.
156 */
157 private void flush(boolean propogate) throws IOException {
158 int avail = base64.avail();
159 if (avail > 0) {
160 byte[] buf = new byte[avail];
161 int c = base64.readResults(buf, 0, avail);
162 if (c > 0) {
163 out.write(buf, 0, c);
164 }
165 }
166 if (propogate) {
167 out.flush();
168 }
169 }
170
171 /**
172 * Flushes this output stream and forces any buffered output bytes to be written out to the stream.
173 *
174 * @throws IOException
175 * if an I/O error occurs.
176 */
177 public void flush() throws IOException {
178 flush(true);
179 }
180
181 /**
182 * Closes this output stream and releases any system resources associated with the stream.
183 *
184 * @throws IOException
185 * if an I/O error occurs.
186 */
187 public void close() throws IOException {
188 // Notify encoder of EOF (-1).
189 if (doEncode) {
190 base64.encode(singleByte, 0, -1);
191 } else {
192 base64.decode(singleByte, 0, -1);
193 }
194 flush();
195 out.close();
196 }
197
198 }