1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.io.channels;
19
20 import java.io.FilterInputStream;
21 import java.io.FilterOutputStream;
22 import java.io.FilterReader;
23 import java.io.IOException;
24 import java.nio.channels.Channel;
25
26 import org.apache.commons.io.build.AbstractStreamBuilder;
27 import org.apache.commons.io.input.ProxyInputStream;
28 import org.apache.commons.io.input.ProxyReader;
29 import org.apache.commons.io.output.ProxyOutputStream;
30 import org.apache.commons.io.output.ProxyWriter;
31
32 /**
33 * A {@link Channel} filter which delegates to the wrapped {@link Channel}.
34 * <p>
35 * 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
36 * additional functionality. The class {@code FilterChannel} itself simply overrides methods of {@code Channel} with versions that pass all requests to the
37 * wrapped channel. Subclasses of {@code FilterChannel} may of course override any methods declared or inherited by {@code FilterChannel}, and may also provide
38 * additional fields and methods.
39 * </p>
40 * <p>
41 * You construct s simple instance with the {@link FilterChannel#FilterChannel(Channel) channel constructor} and more advanced instances through the
42 * {@link Builder}.
43 * </p>
44 *
45 * @param <C> the {@link Channel} type.
46 * @see FilterInputStream
47 * @see FilterOutputStream
48 * @see FilterReader
49 * @see FilterWritableByteChannel
50 * @see ProxyInputStream
51 * @see ProxyOutputStream
52 * @see ProxyReader
53 * @see ProxyWriter
54 * @since 2.22.0
55 */
56 public class FilterChannel<C extends Channel> implements Channel {
57
58 /**
59 * Builds instances of {@link FilterChannel} for subclasses.
60 *
61 * @param <F> The {@link FilterChannel} type.
62 * @param <C> The {@link Channel} type wrapped by the FilterChannel.
63 * @param <B> The builder type.
64 */
65 public abstract static class AbstractBuilder<F extends FilterChannel<C>, C extends Channel, B extends AbstractBuilder<F, C, B>>
66 extends AbstractStreamBuilder<F, AbstractBuilder<F, C, B>> {
67
68 /**
69 * Constructs instance for subclasses.
70 */
71 protected AbstractBuilder() {
72 // empty
73 }
74 }
75
76 /**
77 * Builds instances of {@link FilterChannel}.
78 */
79 public static class Builder extends AbstractBuilder<FilterChannel<Channel>, Channel, Builder> {
80
81 /**
82 * Builds instances of {@link FilterChannel}.
83 */
84 protected Builder() {
85 // empty
86 }
87
88 @Override
89 public FilterChannel<Channel> get() throws IOException {
90 return new FilterChannel<>(this);
91 }
92 }
93
94 /**
95 * Creates a new {@link Builder}.
96 *
97 * @return a new {@link Builder}.
98 */
99 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 }