    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}