TaggedInputStream (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io.input

## Class TaggedInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - org.apache.commons.io.input.ProxyInputStream
      - - org.apache.commons.io.input.TaggedInputStream

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class TaggedInputStream
      extends ProxyInputStream

  An input 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 `IOException`s. See below for an example of using this class.

       TaggedInputStream stream = new TaggedInputStream(...);
       try {
           // Processing that may throw an IOException either from this stream
           // or from some other IO activity like temporary files, etc.
           processStream(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(Throwable)` 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.

       TaggedInputStream stream = new TaggedInputStream(...);
       try {
           processStream(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
    Modifier and Type | Field and Description
    --- | ---
    `private java.io.Serializable` | `tag` The unique tag associated with exceptions from stream.

    - ### Fields inherited from class java.io.FilterInputStream

      `in`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TaggedInputStream(java.io.InputStream proxy)` Creates a tagging decorator for the given input stream.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `handleIOException(java.io.IOException e)` Tags any IOExceptions thrown, wrapping and re-throwing.
    `boolean` | `isCauseOf(java.lang.Throwable exception)` Tests if the given exception was caused by this stream.
    `void` | `throwIfCauseOf(java.lang.Throwable throwable)` Re-throws the original exception thrown by this stream.

    - ### Methods inherited from class org.apache.commons.io.input.ProxyInputStream

      `afterRead, available, beforeRead, close, mark, markSupported, read, read, read, reset, skip`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### tag

          private final java.io.Serializable tag

      The unique tag associated with exceptions from stream.

  - ### Constructor Detail

    - #### TaggedInputStream

          public TaggedInputStream(java.io.InputStream proxy)

      Creates a tagging decorator for the given input stream.
      Parameters:
        `proxy` - input stream to be decorated

  - ### Method Detail

    - #### isCauseOf

          public boolean isCauseOf(java.lang.Throwable 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(java.lang.Throwable throwable)
                              throws java.io.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:
        `throwable` - an exception
      Throws:
        `java.io.IOException` - original exception, if any, thrown by this stream

    - #### handleIOException

          protected void handleIOException(java.io.IOException e)
                                    throws java.io.IOException

      Tags any IOExceptions thrown, wrapping and re-throwing.
      Overrides:
        `handleIOException` in class `ProxyInputStream`
      Parameters:
        `e` - The IOException thrown
      Throws:
        `java.io.IOException` - if an I/O error occurs

Copyright (c) 2002-2016 Apache Software Foundation