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}