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.binary;
19
20 import java.io.OutputStream;
21
22 import org.apache.commons.codec.CodecPolicy;
23
24 /**
25 * Provides Base64 encoding and decoding in a streaming fashion (unlimited size). When encoding the default lineLength
26 * is 76 characters and the default lineEnding is CRLF, but these can be overridden by using the appropriate
27 * constructor.
28 * <p>
29 * The default behavior of the Base64OutputStream is to ENCODE, whereas the default behavior of the Base64InputStream
30 * is to DECODE. But this behavior can be overridden by using a different constructor.
31 * </p>
32 * <p>
33 * This class implements section <cite>6.8. Base64 Content-Transfer-Encoding</cite> from RFC 2045 <cite>Multipurpose
34 * Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</cite> by Freed and Borenstein.
35 * </p>
36 * <p>
37 * Since this class operates directly on byte streams, and not character streams, it is hard-coded to only encode/decode
38 * character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252, UTF-8, etc).
39 * </p>
40 * <p>
41 * <b>Note:</b> It is mandatory to close the stream after the last byte has been written to it, otherwise the
42 * final padding will be omitted and the resulting data will be incomplete/inconsistent.
43 * </p>
44 * <p>
45 * You can set the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a
46 * valid encoding. These can be bits that are unused from the final character or entire characters. The default mode is
47 * lenient decoding.
48 * </p>
49 * <ul>
50 * <li>Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded.
51 * <li>Strict: The decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a valid
52 * encoding. Any unused bits from the final character must be zero. Impossible counts of entire final characters are not
53 * allowed.
54 * </ul>
55 * <p>
56 * When strict decoding is enabled it is expected that the decoded bytes will be re-encoded to a byte array that matches
57 * the original, i.e. no changes occur on the final character. This requires that the input bytes use the same padding
58 * and alphabet as the encoder.
59 * </p>
60 * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
61 * @since 1.4
62 */
63 public class Base64OutputStream extends BaseNCodecOutputStream {
64
65 /**
66 * Creates a Base64OutputStream such that all data written is Base64-encoded to the original provided OutputStream.
67 *
68 * @param outputStream
69 * OutputStream to wrap.
70 */
71 public Base64OutputStream(final OutputStream outputStream) {
72 this(outputStream, true);
73 }
74
75 /**
76 * Creates a Base64OutputStream such that all data written is either Base64-encoded or Base64-decoded to the
77 * original provided OutputStream.
78 *
79 * @param outputStream
80 * OutputStream to wrap.
81 * @param doEncode
82 * true if we should encode all data written to us, false if we should decode.
83 */
84 public Base64OutputStream(final OutputStream outputStream, final boolean doEncode) {
85 super(outputStream, new Base64(false), doEncode);
86 }
87
88 /**
89 * Creates a Base64OutputStream such that all data written is either Base64-encoded or Base64-decoded to the
90 * original provided OutputStream.
91 *
92 * @param outputStream
93 * OutputStream to wrap.
94 * @param doEncode
95 * true if we should encode all data written to us, false if we should decode.
96 * @param lineLength
97 * If doEncode is true, each line of encoded data will contain lineLength characters (rounded down to
98 * the nearest multiple of 4). If lineLength <= 0, the encoded data is not divided into lines. If
99 * doEncode is false, lineLength is ignored.
100 * @param lineSeparator
101 * If doEncode is true, each line of encoded data will be terminated with this byte sequence (e.g. \r\n).
102 * If lineLength <= 0, the lineSeparator is not used. If doEncode is false lineSeparator is ignored.
103 */
104 public Base64OutputStream(final OutputStream outputStream, final boolean doEncode, final int lineLength, final byte[] lineSeparator) {
105 super(outputStream, new Base64(lineLength, lineSeparator), doEncode);
106 }
107
108 /**
109 * Creates a Base64OutputStream such that all data written is either Base64-encoded or Base64-decoded to the
110 * original provided OutputStream.
111 *
112 * @param outputStream
113 * OutputStream to wrap.
114 * @param doEncode
115 * true if we should encode all data written to us, false if we should decode.
116 * @param lineLength
117 * If doEncode is true, each line of encoded data will contain lineLength characters (rounded down to
118 * the nearest multiple of 4). If lineLength <= 0, the encoded data is not divided into lines. If
119 * doEncode is false, lineLength is ignored.
120 * @param lineSeparator
121 * If doEncode is true, each line of encoded data will be terminated with this byte sequence (e.g. \r\n).
122 * If lineLength <= 0, the lineSeparator is not used. If doEncode is false lineSeparator is ignored.
123 * @param decodingPolicy The decoding policy.
124 * @since 1.15
125 */
126 public Base64OutputStream(final OutputStream outputStream, final boolean doEncode, final int lineLength, final byte[] lineSeparator,
127 final CodecPolicy decodingPolicy) {
128 super(outputStream, new Base64(lineLength, lineSeparator, false, decodingPolicy), doEncode);
129 }
130 }