Package 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:
  `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

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `IOException`
  `getCause()`
  Returns the wrapped exception.
  `Serializable`
  `getTag()`
  Returns the serializable tag object.
  `static boolean`
  `isTaggedWith(Throwable throwable, Object tag)`
  Checks whether the given throwable is tagged with the given tag.
  `static void`
  `throwCauseIfTaggedWith(Throwable throwable, 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`

- ## Constructor Details

  - ### TaggedIOException

    public TaggedIOException(IOException original, Serializable tag)
    Constructs a tagged wrapper for the given exception.
    Parameters:
      `original` - the exception to be tagged
      `tag` - tag of this exception

- ## Method Details

  - ### isTaggedWith

    public static boolean isTaggedWith(Throwable throwable, 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 (TaggedIOException.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(Throwable throwable, Object tag) throws 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) {
             TaggedIOException.throwCauseIfTagged(t, tag);
             // handle other kinds of exceptions
         }

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

  - ### getCause

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

  - ### getTag

    public Serializable getTag()
    Returns the serializable tag object.
    Returns:
      tag object