org.apache.commons.io.output
Class TaggedOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.FilterOutputStream
          org.apache.commons.io.output.ProxyOutputStream
              org.apache.commons.io.output.TaggedOutputStream

All Implemented Interfaces:

Closeable, Flushable

public class TaggedOutputStream
extends ProxyOutputStream

An output stream decorator that tags potential exceptions so that the stream that caused the exception can easily be identified. This is done by using the TaggedIOException class to wrap all thrown IOExceptions. See below for an example of using this class.

 TaggedOutputStream stream = new TaggedOutputStream(...);
 try {
     // Processing that may throw an IOException either from this stream
     // or from some other IO activity like temporary files, etc.
     writeToStream(stream);
 } catch (IOException e) {
     if (stream.isCauseOf(e)) {
         // The exception was caused by this stream.
         // Use e.getCause() to get the original exception.
     } else {
         // The exception was caused by something else.
     }
 }
 

Alternatively, the throwIfCauseOf(Exception) method can be used to let higher levels of code handle the exception caused by this stream while other processing errors are being taken care of at this lower level.

 TaggedOutputStream stream = new TaggedOutputStream(...);
 try {
     writeToStream(stream);
 } catch (IOException e) {
     stream.throwIfCauseOf(e);
     // ... or process the exception that was caused by something else
 }
 

Since:

2.0

See Also:

TaggedIOException

Field Summary

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

TaggedOutputStream(OutputStream proxy)
Creates a tagging decorator for the given output stream.

Method Summary

protected void	handleIOException(IOException e) Tags any IOExceptions thrown, wrapping and re-throwing.
boolean	isCauseOf(Exception exception) Tests if the given exception was caused by this stream.
void	throwIfCauseOf(Exception exception) Re-throws the original exception thrown by this stream.

Methods inherited from class org.apache.commons.io.output.ProxyOutputStream

afterWrite, beforeWrite, close, flush, write, write, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TaggedOutputStream

public TaggedOutputStream(OutputStream proxy)

Creates a tagging decorator for the given output stream.

Parameters:

proxy - output stream to be decorated

Method Detail

isCauseOf

public boolean isCauseOf(Exception exception)

Tests if the given exception was caused by this stream.

Parameters:

exception - an exception

Returns:

true if the exception was thrown by this stream, false otherwise

throwIfCauseOf

public void throwIfCauseOf(Exception exception)
                    throws IOException

Re-throws the original exception thrown by this stream. This method first checks whether the given exception is a TaggedIOException wrapper created by this decorator, and then unwraps and throws the original wrapped exception. Returns normally if the exception was not thrown by this stream.

Parameters:

exception - an exception

Throws:

IOException - original exception, if any, thrown by this stream

handleIOException

protected void handleIOException(IOException e)
                          throws IOException

Tags any IOExceptions thrown, wrapping and re-throwing.

Overrides:

handleIOException in class ProxyOutputStream

Parameters:

e - The IOException thrown

Throws:

IOException - if an I/O error occurs