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 /**
23 * Provides Base58 encoding through a stream interface.
24 *
25 * <p>
26 * The default behavior of Base58InputStream is to decode, and the default behavior of Base58OutputStream is to encode. The builder can select either
27 * behavior with {@code setEncode(boolean)}.
28 * </p>
29 *
30 * <p>
31 * Results are available only after EOF. Decoding accepts at most
32 * {@link Base58#DEFAULT_MAX_DECODE_LENGTH} encoded bytes by default and throws {@link java.io.IOException} when an input chunk would exceed the cumulative
33 * limit. To configure the limit, pass a codec built with {@link Base58.Builder#setMaxDecodeLength(int)} to the stream builder's
34 * {@code setBaseNCodec(Base58)} method.
35 * </p>
36 *
37 * <p>
38 * Encoding accepts at most {@link Base58#DEFAULT_MAX_ENCODE_LENGTH} binary bytes by default and throws {@link java.io.IOException} when an input chunk would
39 * exceed that cumulative limit. Configure it with {@link Base58.Builder#setMaxEncodeLength(int)} on the codec passed to {@code setBaseNCodec(Base58)}.
40 * </p>
41 * <p>
42 * The complete input is retained until EOF. Memory usage is proportional to the accumulated input and conversion output. Configure both input limits
43 * appropriately for larger trusted values; encoded output can exceed the decode limit.
44 * </p>
45 *
46 * <p>
47 * Close the output stream or call {@link #eof()} after the last write to complete conversion.
48 * </p>
49 *
50 * @see Base58
51 * @see <a href="https://datatracker.ietf.org/doc/html/draft-msporny-base58-03">The Base58 Encoding Scheme draft-msporny-base58-03</a>
52 * @since 1.22.0
53 */
54 public class Base58OutputStream extends BaseNCodecOutputStream<Base58, Base58OutputStream, Base58OutputStream.Builder> {
55
56 /**
57 * Builds instances of Base58OutputStream.
58 */
59 public static class Builder extends BaseNCodecOutputStream.AbstractBuilder<Base58OutputStream, Base58, Builder> {
60
61 /**
62 * Constructs a new instance.
63 */
64 public Builder() {
65 setEncode(true);
66 }
67
68 /**
69 * Gets a new Base58OutputStream instance with the configured settings.
70 *
71 * @return A new Base58OutputStream.
72 */
73 @Override
74 public Base58OutputStream get() {
75 return new Base58OutputStream(this);
76 }
77
78 /**
79 * Creates a new Base58 codec instance.
80 *
81 * @return A new Base58 codec.
82 */
83 @Override
84 protected Base58 newBaseNCodec() {
85 return new Base58();
86 }
87 }
88
89 /**
90 * Constructs a new Builder.
91 *
92 * @return A new Builder.
93 */
94 public static Builder builder() {
95 return new Builder();
96 }
97
98 private Base58OutputStream(final Builder builder) {
99 super(builder);
100 }
101
102 /**
103 * Constructs a Base58OutputStream such that all data written is Base58-encoded to the original provided OutputStream.
104 *
105 * @param outputStream OutputStream to wrap.
106 */
107 public Base58OutputStream(final OutputStream outputStream) {
108 this(builder().setOutputStream(outputStream));
109 }
110
111 }