1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * https://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20 package org.apache.commons.io.output;
21
22 import java.io.FilterOutputStream;
23 import java.io.IOException;
24 import java.io.OutputStream;
25
26 import org.apache.commons.io.build.AbstractStreamBuilder;
27
28 /**
29 * Re-implements {@link FilterOutputStream#flush()} to do nothing.
30 *
31 * @since 2.22.0
32 */
33 public final class FlushShieldOutputStream extends ProxyOutputStream {
34
35 // @formatter:off
36 /**
37 * Builds a new {@link FlushShieldOutputStream}.
38 *
39 * <p>
40 * Using File IO:
41 * </p>
42 * <pre>{@code
43 * FlushShieldOutputStream s = FlushShieldOutputStream.builder()
44 * .setPath("over/there.out")
45 * .setBufferSize(8192)
46 * .get();
47 * }
48 * </pre>
49 * <p>
50 * Using NIO Path:
51 * </p>
52 * <pre>{@code
53 * FlushShieldOutputStream s = FlushShieldOutputStream.builder()
54 * .setPath("over/there.out")
55 * .setBufferSize(8192)
56 * .get();
57 * }
58 * </pre>
59 *
60 * @see #get()
61 * @since 2.13.0
62 */
63 // @formatter:on
64 public static class Builder extends AbstractStreamBuilder<FlushShieldOutputStream, Builder> {
65
66 /**
67 * Constructs a new builder of {@link FlushShieldOutputStream}.
68 */
69 public Builder() {
70 // empty
71 }
72
73 /**
74 * Builds a new {@link FlushShieldOutputStream}.
75 *
76 * @return a new instance.
77 * @throws IllegalStateException if the {@code origin} is {@code null}.
78 * @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
79 * @throws IOException if an I/O error occurs converting to an {@link OutputStream} using {@link #getOutputStream()}.
80 * @see #getOutputStream()
81 * @see #getBufferSize()
82 * @see #getUnchecked()
83 */
84 @Override
85 public FlushShieldOutputStream get() throws IOException {
86 return new FlushShieldOutputStream(this);
87 }
88
89 }
90
91 /**
92 * Constructs a new builder of {@link FlushShieldOutputStream}.
93 *
94 * @return a new builder of {@link FlushShieldOutputStream}.
95 */
96 public static Builder builder() {
97 return new Builder();
98 }
99
100 @SuppressWarnings("resource") // caller closes.
101 private FlushShieldOutputStream(final Builder builder) throws IOException {
102 super(builder.getOutputStream());
103 }
104
105 /**
106 * Constructs a {@code FlushShieldOutputStream} filter for the specified underlying output stream.
107 *
108 * @param out the underlying output stream to be assigned to the field {@code this.out} for later use, or {@code null} if this instance is to be created
109 * without an underlying stream.
110 */
111 public FlushShieldOutputStream(final OutputStream out) {
112 super(out);
113 }
114
115 @Override
116 public void flush() throws IOException {
117 // shield: do nothing.
118 }
119 }