View Javadoc
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.IOException;
20  import java.io.OutputStream;
21  import java.io.Serializable;
22  import java.util.UUID;
23  
24  import org.apache.commons.io.TaggedIOException;
25  
26  /**
27   * An output stream decorator that tags potential exceptions so that the
28   * stream that caused the exception can easily be identified. This is
29   * done by using the {@link TaggedIOException} class to wrap all thrown
30   * {@link IOException}s. See below for an example of using this class.
31   * <pre>
32   * TaggedOutputStream stream = new TaggedOutputStream(...);
33   * try {
34   *     // Processing that may throw an IOException either from this stream
35   *     // or from some other IO activity like temporary files, etc.
36   *     writeToStream(stream);
37   * } catch (IOException e) {
38   *     if (stream.isCauseOf(e)) {
39   *         // The exception was caused by this stream.
40   *         // Use e.getCause() to get the original exception.
41   *     } else {
42   *         // The exception was caused by something else.
43   *     }
44   * }
45   * </pre>
46   * <p>
47   * Alternatively, the {@link #throwIfCauseOf(Exception)} method can be
48   * used to let higher levels of code handle the exception caused by this
49   * stream while other processing errors are being taken care of at this
50   * lower level.
51   * <pre>
52   * TaggedOutputStream stream = new TaggedOutputStream(...);
53   * try {
54   *     writeToStream(stream);
55   * } catch (IOException e) {
56   *     stream.throwIfCauseOf(e);
57   *     // ... or process the exception that was caused by something else
58   * }
59   * </pre>
60   *
61   * @see TaggedIOException
62   * @since 2.0
63   */
64  public class TaggedOutputStream extends ProxyOutputStream {
65  
66      /**
67       * The unique tag associated with exceptions from stream.
68       */
69      private final Serializable tag = UUID.randomUUID();
70  
71      /**
72       * Creates a tagging decorator for the given output stream.
73       *
74       * @param proxy output stream to be decorated
75       */
76      public TaggedOutputStream(final OutputStream proxy) {
77          super(proxy);
78      }
79  
80      /**
81       * Tests if the given exception was caused by this stream.
82       *
83       * @param exception an exception
84       * @return {@code true} if the exception was thrown by this stream,
85       *         {@code false} otherwise
86       */
87      public boolean isCauseOf(final Exception exception) {
88          return TaggedIOException.isTaggedWith(exception, tag);
89      }
90  
91      /**
92       * Re-throws the original exception thrown by this stream. This method
93       * first checks whether the given exception is a {@link TaggedIOException}
94       * wrapper created by this decorator, and then unwraps and throws the
95       * original wrapped exception. Returns normally if the exception was
96       * not thrown by this stream.
97       *
98       * @param exception an exception
99       * @throws IOException original exception, if any, thrown by this stream
100      */
101     public void throwIfCauseOf(final Exception exception) throws IOException {
102         TaggedIOException.throwCauseIfTaggedWith(exception, tag);
103     }
104 
105     /**
106      * Tags any IOExceptions thrown, wrapping and re-throwing.
107      *
108      * @param e The IOException thrown
109      * @throws IOException if an I/O error occurs
110      */
111     @Override
112     protected void handleIOException(final IOException e) throws IOException {
113         throw new TaggedIOException(e, tag);
114     }
115 
116 }