de.schlichtherle.truezip.io
Class ChainableIOException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.io.IOException
              de.schlichtherle.truezip.io.ChainableIOException

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

FsSyncException

public class ChainableIOException
extends IOException
implements Cloneable

Represents a chain of subsequently occured IOExceptions which have not caused each other.

This class supports chaining I/O exceptions for reasons other than causes (which is a functionality already provided by J2SE 1.4 and later). A chainable I/O exception can be used to implement an algorithm which must be able to continue with some work although one or more I/O exceptions have occured.

For example, when looping through a list of files, an algorithm might encounter an I/O exception when processing a file element in the list. However, it may still be required to process the remaining files in the list before actually throwing the corresponding I/O exception. Hence, whenever this algorithm encounters an I/O exception, it would catch the I/O exception, create a chainable I/O exception for it and continue processing the remainder of the list. Finally, at the end of the algorithm, if any I/O exceptions have occured, the chainable I/O exception would get sorted according to priority (see getPriority() and sortPriority()) and finally thrown. This would allow a client application to filter the I/O exceptions by priority with a simple try-catch statement, ensuring that no other exception of higher priority is in the catched exception chain.

This class is thread-safe.

Author:

Christian Schlichtherle

See Also:

Serialized Form

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

maxPrintExceptions

private static int maxPrintExceptions

PRIORITY_COMP

static final Comparator<ChainableIOException> PRIORITY_COMP

Compares two chainable I/O exceptions in descending order of their priority. If the priority is equal, the elements are compared in descending order of their appearance.

INDEX_COMP

static final Comparator<ChainableIOException> INDEX_COMP

Compares two chainable I/O exceptions in descending order of their appearance.

predecessor

private ChainableIOException predecessor

The tail of this exception chain. Maybe this if the predecessor hasn't been initPredecessor(ChainableIOException) initialized yet or null if there are no more exceptions in this chain.

priority

private final int priority

index

private int index

maxIndex

int maxIndex

ChainableIOException

public ChainableIOException()

ChainableIOException

public ChainableIOException(String message)

ChainableIOException

public ChainableIOException(Throwable cause)

ChainableIOException

public ChainableIOException(String message,
                            Throwable cause)

ChainableIOException

public ChainableIOException(int priority)

ChainableIOException

public ChainableIOException(String message,
                            int priority)

ChainableIOException

public ChainableIOException(Throwable cause,
                            int priority)

ChainableIOException

public ChainableIOException(String message,
                            Throwable cause,
                            int priority)

Constructs a new chainable I/O exception with the given message, cause and priority. The predecessor of this exception remains unknown until initiliazed by calling the method initPredecessor(ChainableIOException).

Parameters:

message - The message for this exception.

cause - The cause exception. A null value is permitted, and indicates that the cause for this exception is nonexistent.

priority - The priority of this exception to be used for priority sorting.

clone

public ChainableIOException clone()

Returns a shallow clone of this exception.

Overrides:

clone in class Object

initCause

public ChainableIOException initCause(Throwable cause)

Overrides:

initCause in class Throwable

initPredecessor

public final ChainableIOException initPredecessor(ChainableIOException predecessor)

Initializes the predecessor of this chainable exception to the given object. This method can be called at most once unless the given predecessor is the same as the previously initialized predecessor.

Parameters:

predecessor - An exception that happened before and is not the cause for this exception! Must be null to indicate that a predecessor does not exist.

Returns:

A reference to this object.

Throws:

IllegalStateException - If the predecessor has already been set.

IllegalArgumentException - If the given predecessor is this instance or has not been initialized with a predecessor itself.

setPredecessor

private void setPredecessor(ChainableIOException predecessor)

getPredecessor

public final ChainableIOException getPredecessor()

Returns the exception chain represented by the predecessing exception, or null if no predecessing exception exists or this property hasn't been initialized yet.

getPriority

public final int getPriority()

Returns the priority of this exception.

sortPriority

public ChainableIOException sortPriority()

Sorts the elements of this exception chain in descending order of their priority. If the priority of two elements is equal, they are sorted in descending order of their appearance.

Returns:

The sorted exception chain, consisting of cloned elements where required to enforce the immutability of this class. This is a non-destructive sort, i.e. elements already in order are guaranteed not to get rearranged. If and only if all elements are in order, this exception chain is returned and no elements are cloned.

sortIndex

public ChainableIOException sortIndex()

Sorts the elements of this exception chain in descending order of their index.

Returns:

The sorted exception chain, consisting of cloned elements where required to enforce the immutability of this class. This is a non-destructive sort, i.e. elements already in order are guaranteed not to get rearranged. If and only if all elements are in order, this exception chain is returned and no elements are cloned.

sort

private ChainableIOException sort(Comparator<ChainableIOException> cmp)

insert

private ChainableIOException insert(ChainableIOException element,
                                    Comparator<ChainableIOException> cmp)

printStackTrace

public void printStackTrace(PrintStream s)

Prints up to getMaxPrintExceptions() exceptions in this chain to the provided PrintStream.

Exceptions are printed in ascending order of this chain. If this chain has not been sorted, this results in the exceptions being printed in order of their appearance.

If more exceptions are in this chain than are allowed to be printed, then the printed message starts with a line indicating the number of exceptions which have been omitted from the beginning of this chain. Thus, this exception is always printed as the last exception in the list.

Overrides:

printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s,
                            int maxExceptions)

Prints up to maxExceptions() exceptions in this chain to the provided PrintStream.

Exceptions are printed in ascending order of this chain. If this chain has not been sorted, this results in the exceptions being printed in order of their appearance.

If more exceptions are in this chain than are allowed to be printed, then the printed message starts with a line indicating the number of exceptions which have been omitted from the beginning of this chain. Thus, this exception is always printed as the last exception in the list.

getNumExceptions

private int getNumExceptions()

printStackTrace

public void printStackTrace(PrintWriter s)

Prints up to getMaxPrintExceptions() exceptions in this chain to the provided PrintStream.

Exceptions are printed in ascending order of this chain. If this chain has not been sorted, this results in the exceptions being printed in order of their appearance.

If more exceptions are in this chain than are allowed to be printed, then the printed message starts with a line indicating the number of exceptions which have been omitted from the beginning of this chain. Thus, this exception is always printed as the last exception in the list.

Overrides:

printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintWriter s,
                            int maxExceptions)

Prints up to maxExceptions() exceptions in this chain to the provided PrintStream.

Exceptions are printed in ascending order of this chain. If this chain has not been sorted, this results in the exceptions being printed in order of their appearance.

If more exceptions are in this chain than are allowed to be printed, then the printed message starts with a line indicating the number of exceptions which have been omitted from the beginning of this chain. Thus, this exception is always printed as the last exception in the list.

getMaxPrintExceptions

public static int getMaxPrintExceptions()

See Also:

printStackTrace(PrintStream), printStackTrace(PrintWriter)

setMaxPrintExceptions

public static void setMaxPrintExceptions(int maxPrintExcepions)

See Also:

printStackTrace(PrintStream), printStackTrace(PrintWriter)