ProxyCollectionWriter.java

  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;

  19. import java.io.FilterWriter;
  20. import java.io.IOException;
  21. import java.io.Writer;
  22. import java.util.Collection;

  24. import org.apache.commons.io.IOUtils;

  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 {

  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.     }

  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.     }

  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.     }

  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.     @Override
  81.     public Writer append(final char c) throws IOException {
  82.         try {
  83.             beforeWrite(1);
  84.             super.append(c);
  85.             afterWrite(1);
  86.         } catch (final IOException e) {
  87.             handleIOException(e);
  88.         }
  89.         return this;
  90.     }

  92.     /**
  93.      * Invokes the delegates' {@code append(CharSequence)} methods.
  94.      *
  95.      * @param csq The character sequence to write
  96.      * @return this writer
  97.      * @throws IOException if an I/O error occurs.
  98.      */
  99.     @Override
  100.     public Writer append(final CharSequence csq) throws IOException {
  101.         try {
  102.             final int len = IOUtils.length(csq);
  103.             beforeWrite(len);
  104.             super.append(csq);
  105.             afterWrite(len);
  106.         } catch (final IOException e) {
  107.             handleIOException(e);
  108.         }
  109.         return this;
  110.     }

  112.     /**
  113.      * Invokes the delegates' {@code append(CharSequence, int, int)} methods.
  114.      *
  115.      * @param csq   The character sequence to write
  116.      * @param start The index of the first character to write
  117.      * @param end   The index of the first character to write (exclusive)
  118.      * @return this writer
  119.      * @throws IOException if an I/O error occurs.
  120.      */
  121.     @Override
  122.     public Writer append(final CharSequence csq, final int start, final int end) throws IOException {
  123.         try {
  124.             beforeWrite(end - start);
  125.             super.append(csq, start, end);
  126.             afterWrite(end - start);
  127.         } catch (final IOException e) {
  128.             handleIOException(e);
  129.         }
  130.         return this;
  131.     }

  133.     /**
  134.      * Invoked by the write methods before the call is proxied. The number of chars to be written (1 for the
  135.      * {@link #write(int)} method, buffer length for {@link #write(char[])}, etc.) is given as an argument.
  136.      * <p>
  137.      * Subclasses can override this method to add common pre-processing functionality without having to override all the
  138.      * write methods. The default implementation does nothing.
  139.      * </p>
  140.      *
  141.      * @param n number of chars to be written
  142.      * @throws IOException if the pre-processing fails
  143.      */
  144.     @SuppressWarnings("unused") // Possibly thrown from subclasses.
  145.     protected void beforeWrite(final int n) throws IOException {
  146.         // noop
  147.     }

  149.     /**
  150.      * Invokes the delegate's {@code close()} method.
  151.      *
  152.      * @throws IOException if an I/O error occurs.
  153.      */
  154.     @Override
  155.     public void close() throws IOException {
  156.         try {
  157.             super.close();
  158.         } catch (final IOException e) {
  159.             handleIOException(e);
  160.         }
  161.     }

  163.     /**
  164.      * Invokes the delegate's {@code flush()} method.
  165.      *
  166.      * @throws IOException if an I/O error occurs.
  167.      */
  168.     @Override
  169.     public void flush() throws IOException {
  170.         try {
  171.             super.flush();
  172.         } catch (final IOException e) {
  173.             handleIOException(e);
  174.         }
  175.     }

  177.     /**
  178.      * Handle any IOExceptions thrown.
  179.      * <p>
  180.      * This method provides a point to implement custom exception handling. The default behavior is to re-throw the
  181.      * exception.
  182.      * </p>
  183.      *
  184.      * @param e The IOException thrown
  185.      * @throws IOException if an I/O error occurs.
  186.      */
  187.     protected void handleIOException(final IOException e) throws IOException {
  188.         throw e;
  189.     }

  191.     /**
  192.      * Invokes the delegate's {@code write(char[])} method.
  193.      *
  194.      * @param cbuf the characters to write
  195.      * @throws IOException if an I/O error occurs.
  196.      */
  197.     @Override
  198.     public void write(final char[] cbuf) throws IOException {
  199.         try {
  200.             final int len = IOUtils.length(cbuf);
  201.             beforeWrite(len);
  202.             super.write(cbuf);
  203.             afterWrite(len);
  204.         } catch (final IOException e) {
  205.             handleIOException(e);
  206.         }
  207.     }

  209.     /**
  210.      * Invokes the delegate's {@code write(char[], int, int)} method.
  211.      *
  212.      * @param cbuf the characters to write
  213.      * @param off  The start offset
  214.      * @param len  The number of characters to write
  215.      * @throws IOException if an I/O error occurs.
  216.      */
  217.     @Override
  218.     public void write(final char[] cbuf, final int off, final int len) throws IOException {
  219.         try {
  220.             beforeWrite(len);
  221.             super.write(cbuf, off, len);
  222.             afterWrite(len);
  223.         } catch (final IOException e) {
  224.             handleIOException(e);
  225.         }
  226.     }

  228.     /**
  229.      * Invokes the delegate's {@code write(int)} method.
  230.      *
  231.      * @param c the character to write
  232.      * @throws IOException if an I/O error occurs.
  233.      */
  234.     @Override
  235.     public void write(final int c) throws IOException {
  236.         try {
  237.             beforeWrite(1);
  238.             super.write(c);
  239.             afterWrite(1);
  240.         } catch (final IOException e) {
  241.             handleIOException(e);
  242.         }
  243.     }

  245.     /**
  246.      * Invokes the delegate's {@code write(String)} method.
  247.      *
  248.      * @param str the string to write
  249.      * @throws IOException if an I/O error occurs.
  250.      */
  251.     @Override
  252.     public void write(final String str) throws IOException {
  253.         try {
  254.             final int len = IOUtils.length(str);
  255.             beforeWrite(len);
  256.             super.write(str);
  257.             afterWrite(len);
  258.         } catch (final IOException e) {
  259.             handleIOException(e);
  260.         }
  261.     }

  263.     /**
  264.      * Invokes the delegate's {@code write(String)} method.
  265.      *
  266.      * @param str the string to write
  267.      * @param off The start offset
  268.      * @param len The number of characters to write
  269.      * @throws IOException if an I/O error occurs.
  270.      */
  271.     @Override
  272.     public void write(final String str, final int off, final int len) throws IOException {
  273.         try {
  274.             beforeWrite(len);
  275.             super.write(str, off, len);
  276.             afterWrite(len);
  277.         } catch (final IOException e) {
  278.             handleIOException(e);
  279.         }
  280.     }

  282. }
Created with JaCoCo 0.8.12.202403310830