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 * http://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 package org.apache.commons.io.output; 18 19 import java.io.FilterWriter; 20 import java.io.IOException; 21 import java.io.Writer; 22 import java.util.Collection; 23 24 import org.apache.commons.io.IOUtils; 25 26 /** 27 * A Proxy stream collection which acts as expected, that is it passes the method calls on to the proxied streams and 28 * doesn't change which methods are being called. It is an alternative base class to {@link FilterWriter} and 29 * {@link FilterCollectionWriter} to increase reusability, because FilterWriter changes the methods being called, such 30 * as {@code write(char[])} to {@code write(char[], int, int)} and {@code write(String)} to 31 * {@code write(String, int, int)}. This is in contrast to {@link ProxyWriter} which is backed by a single 32 * {@link Writer}. 33 * 34 * @since 2.7 35 */ 36 public class ProxyCollectionWriter extends FilterCollectionWriter { 37 38 /** 39 * Constructs a new proxy collection writer. 40 * 41 * @param writers Writers object to provide the underlying targets. 42 */ 43 public ProxyCollectionWriter(final Collection<Writer> writers) { 44 super(writers); 45 } 46 47 /** 48 * Constructs a new proxy collection writer. 49 * 50 * @param writers Writers to provide the underlying targets. 51 */ 52 public ProxyCollectionWriter(final Writer... writers) { 53 super(writers); 54 } 55 56 /** 57 * Invoked by the write methods after the proxied call has returned successfully. The number of chars written (1 for 58 * the {@link #write(int)} method, buffer length for {@link #write(char[])}, etc.) is given as an argument. 59 * <p> 60 * Subclasses can override this method to add common post-processing functionality without having to override all 61 * the write methods. The default implementation does nothing. 62 * </p> 63 * 64 * @param n number of chars written 65 * @throws IOException if the post-processing fails 66 */ 67 @SuppressWarnings("unused") // Possibly thrown from subclasses. 68 protected void afterWrite(final int n) throws IOException { 69 // noop 70 } 71 72 /** 73 * Invokes the delegates' {@code append(char)} methods. 74 * 75 * @param c The character to write 76 * @return this writer 77 * @throws IOException if an I/O error occurs. 78 * @since 2.0 79 */ 80 @SuppressWarnings("resource") // Fluent API. 81 @Override 82 public Writer append(final char c) throws IOException { 83 try { 84 beforeWrite(1); 85 super.append(c); 86 afterWrite(1); 87 } catch (final IOException e) { 88 handleIOException(e); 89 } 90 return this; 91 } 92 93 /** 94 * Invokes the delegates' {@code append(CharSequence)} methods. 95 * 96 * @param csq The character sequence to write 97 * @return this writer 98 * @throws IOException if an I/O error occurs. 99 */ 100 @SuppressWarnings("resource") // Fluent API. 101 @Override 102 public Writer append(final CharSequence csq) throws IOException { 103 try { 104 final int len = IOUtils.length(csq); 105 beforeWrite(len); 106 super.append(csq); 107 afterWrite(len); 108 } catch (final IOException e) { 109 handleIOException(e); 110 } 111 return this; 112 } 113 114 /** 115 * Invokes the delegates' {@code append(CharSequence, int, int)} methods. 116 * 117 * @param csq The character sequence to write 118 * @param start The index of the first character to write 119 * @param end The index of the first character to write (exclusive) 120 * @return this writer 121 * @throws IOException if an I/O error occurs. 122 */ 123 @SuppressWarnings("resource") // Fluent API. 124 @Override 125 public Writer append(final CharSequence csq, final int start, final int end) throws IOException { 126 try { 127 beforeWrite(end - start); 128 super.append(csq, start, end); 129 afterWrite(end - start); 130 } catch (final IOException e) { 131 handleIOException(e); 132 } 133 return this; 134 } 135 136 /** 137 * Invoked by the write methods before the call is proxied. The number of chars to be written (1 for the 138 * {@link #write(int)} method, buffer length for {@link #write(char[])}, etc.) is given as an argument. 139 * <p> 140 * Subclasses can override this method to add common pre-processing functionality without having to override all the 141 * write methods. The default implementation does nothing. 142 * </p> 143 * 144 * @param n number of chars to be written 145 * @throws IOException if the pre-processing fails 146 */ 147 @SuppressWarnings("unused") // Possibly thrown from subclasses. 148 protected void beforeWrite(final int n) throws IOException { 149 // noop 150 } 151 152 /** 153 * Invokes the delegate's {@code close()} method. 154 * 155 * @throws IOException if an I/O error occurs. 156 */ 157 @Override 158 public void close() throws IOException { 159 try { 160 super.close(); 161 } catch (final IOException e) { 162 handleIOException(e); 163 } 164 } 165 166 /** 167 * Invokes the delegate's {@code flush()} method. 168 * 169 * @throws IOException if an I/O error occurs. 170 */ 171 @Override 172 public void flush() throws IOException { 173 try { 174 super.flush(); 175 } catch (final IOException e) { 176 handleIOException(e); 177 } 178 } 179 180 /** 181 * Handle any IOExceptions thrown. 182 * <p> 183 * This method provides a point to implement custom exception handling. The default behavior is to re-throw the 184 * exception. 185 * </p> 186 * 187 * @param e The IOException thrown 188 * @throws IOException if an I/O error occurs. 189 */ 190 protected void handleIOException(final IOException e) throws IOException { 191 throw e; 192 } 193 194 /** 195 * Invokes the delegate's {@code write(char[])} method. 196 * 197 * @param cbuf the characters to write 198 * @throws IOException if an I/O error occurs. 199 */ 200 @Override 201 public void write(final char[] cbuf) throws IOException { 202 try { 203 final int len = IOUtils.length(cbuf); 204 beforeWrite(len); 205 super.write(cbuf); 206 afterWrite(len); 207 } catch (final IOException e) { 208 handleIOException(e); 209 } 210 } 211 212 /** 213 * Invokes the delegate's {@code write(char[], int, int)} method. 214 * 215 * @param cbuf the characters to write 216 * @param off The start offset 217 * @param len The number of characters to write 218 * @throws IOException if an I/O error occurs. 219 */ 220 @Override 221 public void write(final char[] cbuf, final int off, final int len) throws IOException { 222 try { 223 beforeWrite(len); 224 super.write(cbuf, off, len); 225 afterWrite(len); 226 } catch (final IOException e) { 227 handleIOException(e); 228 } 229 } 230 231 /** 232 * Invokes the delegate's {@code write(int)} method. 233 * 234 * @param c the character to write 235 * @throws IOException if an I/O error occurs. 236 */ 237 @Override 238 public void write(final int c) throws IOException { 239 try { 240 beforeWrite(1); 241 super.write(c); 242 afterWrite(1); 243 } catch (final IOException e) { 244 handleIOException(e); 245 } 246 } 247 248 /** 249 * Invokes the delegate's {@code write(String)} method. 250 * 251 * @param str the string to write 252 * @throws IOException if an I/O error occurs. 253 */ 254 @Override 255 public void write(final String str) throws IOException { 256 try { 257 final int len = IOUtils.length(str); 258 beforeWrite(len); 259 super.write(str); 260 afterWrite(len); 261 } catch (final IOException e) { 262 handleIOException(e); 263 } 264 } 265 266 /** 267 * Invokes the delegate's {@code write(String)} method. 268 * 269 * @param str the string to write 270 * @param off The start offset 271 * @param len The number of characters to write 272 * @throws IOException if an I/O error occurs. 273 */ 274 @Override 275 public void write(final String str, final int off, final int len) throws IOException { 276 try { 277 beforeWrite(len); 278 super.write(str, off, len); 279 afterWrite(len); 280 } catch (final IOException e) { 281 handleIOException(e); 282 } 283 } 284 285 }