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.FilterOutputStream; 20 import java.io.IOException; 21 import java.io.OutputStream; 22 23 import org.apache.commons.io.IOUtils; 24 25 /** 26 * A Proxy stream which acts as expected, that is it passes the method 27 * calls on to the proxied stream and doesn't change which methods are 28 * being called. It is an alternative base class to FilterOutputStream 29 * to increase reusability. 30 * <p> 31 * See the protected methods for ways in which a subclass can easily decorate 32 * a stream with custom pre-, post- or error processing functionality. 33 * </p> 34 */ 35 public class ProxyOutputStream extends FilterOutputStream { 36 37 /** 38 * Constructs a new ProxyOutputStream. 39 * 40 * @param proxy the OutputStream to delegate to 41 */ 42 public ProxyOutputStream(final OutputStream proxy) { 43 super(proxy); 44 // the proxy is stored in a protected superclass variable named 'out' 45 } 46 47 /** 48 * Invoked by the write methods after the proxied call has returned 49 * successfully. The number of bytes written (1 for the 50 * {@link #write(int)} method, buffer length for {@link #write(byte[])}, 51 * etc.) is given as an argument. 52 * <p> 53 * Subclasses can override this method to add common post-processing 54 * functionality without having to override all the write methods. 55 * The default implementation does nothing. 56 * 57 * @since 2.0 58 * @param n number of bytes written 59 * @throws IOException if the post-processing fails 60 */ 61 @SuppressWarnings("unused") // Possibly thrown from subclasses. 62 protected void afterWrite(final int n) throws IOException { 63 // noop 64 } 65 66 /** 67 * Invoked by the write methods before the call is proxied. The number 68 * of bytes to be written (1 for the {@link #write(int)} method, buffer 69 * length for {@link #write(byte[])}, etc.) is given as an argument. 70 * <p> 71 * Subclasses can override this method to add common pre-processing 72 * functionality without having to override all the write methods. 73 * The default implementation does nothing. 74 * 75 * @since 2.0 76 * @param n number of bytes to be written 77 * @throws IOException if the pre-processing fails 78 */ 79 @SuppressWarnings("unused") // Possibly thrown from subclasses. 80 protected void beforeWrite(final int n) throws IOException { 81 // noop 82 } 83 84 /** 85 * Invokes the delegate's {@code close()} method. 86 * @throws IOException if an I/O error occurs. 87 */ 88 @Override 89 public void close() throws IOException { 90 IOUtils.close(out, this::handleIOException); 91 } 92 93 /** 94 * Invokes the delegate's {@code flush()} method. 95 * @throws IOException if an I/O error occurs. 96 */ 97 @Override 98 public void flush() throws IOException { 99 try { 100 out.flush(); 101 } catch (final IOException e) { 102 handleIOException(e); 103 } 104 } 105 106 /** 107 * Handle any IOExceptions thrown. 108 * <p> 109 * This method provides a point to implement custom exception 110 * handling. The default behavior is to re-throw the exception. 111 * @param e The IOException thrown 112 * @throws IOException if an I/O error occurs. 113 * @since 2.0 114 */ 115 protected void handleIOException(final IOException e) throws IOException { 116 throw e; 117 } 118 119 /** 120 * Invokes the delegate's {@code write(byte[])} method. 121 * @param bts the bytes to write 122 * @throws IOException if an I/O error occurs. 123 */ 124 @Override 125 public void write(final byte[] bts) throws IOException { 126 try { 127 final int len = IOUtils.length(bts); 128 beforeWrite(len); 129 out.write(bts); 130 afterWrite(len); 131 } catch (final IOException e) { 132 handleIOException(e); 133 } 134 } 135 136 /** 137 * Invokes the delegate's {@code write(byte[])} method. 138 * @param bts the bytes to write 139 * @param st The start offset 140 * @param end The number of bytes to write 141 * @throws IOException if an I/O error occurs. 142 */ 143 @Override 144 public void write(final byte[] bts, final int st, final int end) throws IOException { 145 try { 146 beforeWrite(end); 147 out.write(bts, st, end); 148 afterWrite(end); 149 } catch (final IOException e) { 150 handleIOException(e); 151 } 152 } 153 154 /** 155 * Invokes the delegate's {@code write(int)} method. 156 * @param idx the byte to write 157 * @throws IOException if an I/O error occurs. 158 */ 159 @Override 160 public void write(final int idx) throws IOException { 161 try { 162 beforeWrite(1); 163 out.write(idx); 164 afterWrite(1); 165 } catch (final IOException e) { 166 handleIOException(e); 167 } 168 } 169 170 }