001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   https://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020package org.apache.commons.io.output;
021
022import java.io.FilterOutputStream;
023import java.io.IOException;
024import java.io.OutputStream;
025
026import org.apache.commons.io.build.AbstractStreamBuilder;
027
028/**
029 * Re-implements {@link FilterOutputStream#flush()} to do nothing.
030 *
031 * @since 2.22.0
032 */
033public final class FlushShieldOutputStream extends ProxyOutputStream {
034
035    // @formatter:off
036    /**
037     * Builds a new {@link FlushShieldOutputStream}.
038     *
039     * <p>
040     * Using File IO:
041     * </p>
042     * <pre>{@code
043     * FlushShieldOutputStream s = FlushShieldOutputStream.builder()
044     *   .setPath("over/there.out")
045     *   .setBufferSize(8192)
046     *   .get();
047     * }
048     * </pre>
049     * <p>
050     * Using NIO Path:
051     * </p>
052     * <pre>{@code
053     * FlushShieldOutputStream s = FlushShieldOutputStream.builder()
054     *   .setPath("over/there.out")
055     *   .setBufferSize(8192)
056     *   .get();
057     * }
058     * </pre>
059     *
060     * @see #get()
061     * @since 2.13.0
062     */
063    // @formatter:on
064    public static class Builder extends AbstractStreamBuilder<FlushShieldOutputStream, Builder> {
065
066        /**
067         * Constructs a new builder of {@link FlushShieldOutputStream}.
068         */
069        public Builder() {
070            // empty
071        }
072
073        /**
074         * Builds a new {@link FlushShieldOutputStream}.
075         *
076         * @return a new instance.
077         * @throws IllegalStateException         if the {@code origin} is {@code null}.
078         * @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
079         * @throws IOException                   if an I/O error occurs converting to an {@link OutputStream} using {@link #getOutputStream()}.
080         * @see #getOutputStream()
081         * @see #getBufferSize()
082         * @see #getUnchecked()
083         */
084        @Override
085        public FlushShieldOutputStream get() throws IOException {
086            return new FlushShieldOutputStream(this);
087        }
088
089    }
090
091    /**
092     * Constructs a new builder of {@link FlushShieldOutputStream}.
093     *
094     * @return a new builder of {@link FlushShieldOutputStream}.
095     */
096    public static Builder builder() {
097        return new Builder();
098    }
099
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}