    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017
    018package org.apache.commons.io.channels;
    019
    020import java.io.FilterInputStream;
    021import java.io.FilterOutputStream;
    022import java.io.FilterReader;
    023import java.io.IOException;
    024import java.nio.channels.Channel;
    025
    026import org.apache.commons.io.build.AbstractStreamBuilder;
    027import org.apache.commons.io.input.ProxyInputStream;
    028import org.apache.commons.io.input.ProxyReader;
    029import org.apache.commons.io.output.ProxyOutputStream;
    030import org.apache.commons.io.output.ProxyWriter;
    031
    032/**
    033 * A {@link Channel} filter which delegates to the wrapped {@link Channel}.
    034 * <p>
    035 * A {@code FilterChannel} wraps some other channel, which it uses as its basic source of data, possibly transforming the data along the way or providing
    036 * additional functionality. The class {@code FilterChannel} itself simply overrides methods of {@code Channel} with versions that pass all requests to the
    037 * wrapped channel. Subclasses of {@code FilterChannel} may of course override any methods declared or inherited by {@code FilterChannel}, and may also provide
    038 * additional fields and methods.
    039 * </p>
    040 * <p>
    041 * You construct s simple instance with the {@link FilterChannel#FilterChannel(Channel) channel constructor} and more advanced instances through the
    042 * {@link Builder}.
    043 * </p>
    044 *
    045 * @param <C> the {@link Channel} type.
    046 * @see FilterInputStream
    047 * @see FilterOutputStream
    048 * @see FilterReader
    049 * @see FilterWritableByteChannel
    050 * @see ProxyInputStream
    051 * @see ProxyOutputStream
    052 * @see ProxyReader
    053 * @see ProxyWriter
    054 * @since 2.22.0
    055 */
    056public class FilterChannel<C extends Channel> implements Channel {
    057
    058    /**
    059     * Builds instances of {@link FilterChannel} for subclasses.
    060     *
    061     * @param <F> The {@link FilterChannel} type.
    062     * @param <C> The {@link Channel} type wrapped by the FilterChannel.
    063     * @param <B> The builder type.
    064     */
    065    public abstract static class AbstractBuilder<F extends FilterChannel<C>, C extends Channel, B extends AbstractBuilder<F, C, B>>
    066            extends AbstractStreamBuilder<F, AbstractBuilder<F, C, B>> {
    067
    068        /**
    069         * Constructs instance for subclasses.
    070         */
    071        protected AbstractBuilder() {
    072            // empty
    073        }
    074    }
    075
    076    /**
    077     * Builds instances of {@link FilterChannel}.
    078     */
    079    public static class Builder extends AbstractBuilder<FilterChannel<Channel>, Channel, Builder> {
    080
    081        /**
    082         * Builds instances of {@link FilterChannel}.
    083         */
    084        protected Builder() {
    085            // empty
    086        }
    087
    088        @Override
    089        public FilterChannel<Channel> get() throws IOException {
    090            return new FilterChannel<>(this);
    091        }
    092    }
    093
    094    /**
    095     * Creates a new {@link Builder}.
    096     *
    097     * @return a new {@link Builder}.
    098     */
    099    public static Builder forChannel() {
    100        return new Builder();
    101    }
    102
    103    final C channel;
    104
    105    /**
    106     * Constructs a new instance.
    107     *
    108     * @param builder The source builder.
    109     * @throws IOException if an I/O error occurs.
    110     */
    111    @SuppressWarnings("unchecked")
    112    FilterChannel(final AbstractBuilder<?, ?, ?> builder) throws IOException {
    113        channel = (C) builder.getChannel(Channel.class);
    114    }
    115
    116    /**
    117     * Constructs a new instance.
    118     *
    119     * @param channel The channel to wrap.
    120     */
    121    public FilterChannel(final C channel) {
    122        this.channel = channel;
    123    }
    124
    125    @Override
    126    public void close() throws IOException {
    127        channel.close();
    128    }
    129
    130    @Override
    131    public boolean isOpen() {
    132        return channel.isOpen();
    133    }
    134
    135    /**
    136     * Unwraps this instance by returning the underlying {@link Channel} of type {@code C}.
    137     * <p>
    138     * Use with caution.
    139     * </p>
    140     *
    141     * @return the underlying channel of type {@code C}.
    142     */
    143    public C unwrap() {
    144        return channel;
    145    }
    146}