de.schlichtherle.io
Class ChainableIOException

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

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

ArchiveException

public class ChainableIOException
extends IOException
implements Cloneable

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

For example, when looping through a list of files, an algorithm might encounter an IOException 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 IOException. Hence, whenever this algorithm encounters an IOException, it would catch the IOException, create a ChainableIOException for it and continue processing the remainder of the list. Finally, at the end of the algorithm, if any IOExceptions have occured, the ChainableIOException chain would get sorted according to priority (see getPriority() and sortPriority()) and finally thrown. This would allow a client application to filter the exceptions by priority with a simple try-catch statement, ensuring that no other exception of higher priority is in the catched exception chain.

Note: This is not related to the cause concept of exceptions in J2SE 1.4 and higher. Exceptions chained by this class are not causes of each other, but have just been merely collected over time and then thrown as one exception (list).

Since:

TrueZIP 6.0 (generalized from the former ArchiveControllerException).

Author:

Christian Schlichtherle

See Also:

File.update(), File.umount(), Serialized Form

PRIORITY_COMP

static final Comparator PRIORITY_COMP

Compares two ZIP controller exceptions in descending order of their priority. If the priority is equal, the elements are compared in descending order of their appearance.

APPEARANCE_COMP

static final Comparator APPEARANCE_COMP

Compares two ZIP controller exceptions in descending order of their appearance.

maxPrintExceptions

private static int maxPrintExceptions

prior

private ChainableIOException prior

The tail chain of this exception chain. Maybe null if there are no more exceptions. If this exception chain has not been reordered, the head of the tail is either null or an exception which occured before this exception was created.

Please note that this is totally unrelated to a possible cause for this exception!

appearance

private final int appearance

maxAppearance

int maxAppearance

ChainableIOException

public ChainableIOException(ChainableIOException priorException)

Constructs a new exception with the specified prior exception.

Parameters:

priorException - An exception that happened before and that was caught - may be null.

See Also:

ChainableIOException

ChainableIOException

public ChainableIOException(ChainableIOException priorException,
                            String message)

Constructs a new exception with the specified prior exception and a message.

Parameters:

priorException - An exception that happened before and that was caught - may be null.

message - The message for this exception.

See Also:

ChainableIOException

ChainableIOException

public ChainableIOException(ChainableIOException priorException,
                            IOException cause)

Constructs a new exception with the specified prior exception and the cause.

Parameters:

priorException - An exception that happened before and that was caught - may be null.

cause - The cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.).

See Also:

ChainableIOException

ChainableIOException

public ChainableIOException(ChainableIOException priorException,
                            String message,
                            IOException cause)

Constructs a new exception with the specified prior exception, a message and a cause.

Parameters:

priorException - An exception that happened before and that was caught - may be null.

message - The message for this exception.

cause - The cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.).

See Also:

ChainableIOException

clone

public Object clone()

Returns a shallow clone of this exception.

Overrides:

clone in class Object

getPriority

public int getPriority()

Returns the priority for this class of exception. This should always return the same value for all instances of a particular class.

Returns:

0 for all instances of this class.

getAppearance

public final int getAppearance()

Returns:

The order of appearance for this ZIP exception.

getPrior

public ChainableIOException getPrior()

Returns:

The exception chain represented by the prior exception, or null if no prior exception exists.

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.

sortAppearance

public ChainableIOException sortAppearance()

Sorts the elements of this exception chain 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.

sort

private ChainableIOException sort(Comparator comp)

insert

private ChainableIOException insert(ChainableIOException element,
                                    Comparator comp)

initCause

public Throwable initCause(IOException cause)

Calls initCause((IOException) cause).

Throws:

ClassCastException - If cause is not an instance of IOException.

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)