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