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

org.apache.commons.io

## Class TaggedIOException

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Exception
    - - java.io.IOException
      - - org.apache.commons.io.IOExceptionWithCause
        - - org.apache.commons.io.TaggedIOException

- All Implemented Interfaces:
    java.io.Serializable

      public class TaggedIOException
      extends IOExceptionWithCause

  An `IOException` decorator that adds a serializable tag to the wrapped exception. Both the tag and the original exception can be used to determine further processing when this exception is caught.
  Since:
    2.0
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static long` | `serialVersionUID` Generated serial version UID.
    `private java.io.Serializable` | `tag` The tag of this exception.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TaggedIOException(java.io.IOException original, java.io.Serializable tag)` Creates a tagged wrapper for the given exception.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.io.IOException` | `getCause()` Returns the wrapped exception.
    `java.io.Serializable` | `getTag()` Returns the serializable tag object.
    `static boolean` | `isTaggedWith(java.lang.Throwable throwable, java.lang.Object tag)` Checks whether the given throwable is tagged with the given tag.
    `static void` | `throwCauseIfTaggedWith(java.lang.Throwable throwable, java.lang.Object tag)` Throws the original `IOException` if the given throwable is a `TaggedIOException` decorator the given tag.

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

      `addSuppressed, fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

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

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

- - ### Field Detail

    - #### serialVersionUID

          private static final long serialVersionUID

      Generated serial version UID.
      See Also:
        Constant Field Values

    - #### tag

          private final java.io.Serializable tag

      The tag of this exception.

  - ### Constructor Detail

    - #### TaggedIOException

          public TaggedIOException(java.io.IOException original,
                           java.io.Serializable tag)

      Creates a tagged wrapper for the given exception.
      Parameters:
        `original` - the exception to be tagged
        `tag` - tag of this exception

  - ### Method Detail

    - #### isTaggedWith

          public static boolean isTaggedWith(java.lang.Throwable throwable,
                             java.lang.Object tag)

      Checks whether the given throwable is tagged with the given tag.

      This check can only succeed if the throwable is a `TaggedIOException` and the tag is `Serializable`, but the argument types are intentionally more generic to make it easier to use this method without type casts.

      A typical use for this method is in a `catch` block to determine how a caught exception should be handled:

           Serializable tag = ...;
           try {
               ...;
           } catch (Throwable t) {
               if (TaggedIOExcepton.isTaggedWith(t, tag)) {
                   // special processing for tagged exception
               } else {
                   // handling of other kinds of exceptions
               }
           }

      Parameters:
        `throwable` - The Throwable object to check
        `tag` - tag object
      Returns:
        `true` if the throwable has the specified tag, otherwise `false`

    - #### throwCauseIfTaggedWith

          public static void throwCauseIfTaggedWith(java.lang.Throwable throwable,
                                    java.lang.Object tag)
                                             throws java.io.IOException

      Throws the original `IOException` if the given throwable is a `TaggedIOException` decorator the given tag. Does nothing if the given throwable is of a different type or if it is tagged with some other tag.

      This method is typically used in a `catch` block to selectively rethrow tagged exceptions.

           Serializable tag = ...;
           try {
               ...;
           } catch (Throwable t) {
               TaggedIOExcepton.throwCauseIfTagged(t, tag);
               // handle other kinds of exceptions
           }

      Parameters:
        `throwable` - an exception
        `tag` - tag object
      Throws:
        `java.io.IOException` - original exception from the tagged decorator, if any

    - #### getTag

          public java.io.Serializable getTag()

      Returns the serializable tag object.
      Returns:
        tag object

    - #### getCause

          public java.io.IOException getCause()

      Returns the wrapped exception. The only difference to the overridden `Throwable.getCause()` method is the narrower return type.
      Overrides:
        `getCause` in class `java.lang.Throwable`
      Returns:
        wrapped exception

Copyright (c) 2002-2016 Apache Software Foundation