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).

Version:

TrueZIP 6.7

Author:

Christian Schlichtherle

See Also:

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

Constructor Summary

ChainableIOException(ChainableIOException priorException)
Constructs a new exception with the specified prior exception.

ChainableIOException(ChainableIOException priorException, IOException cause)
Constructs a new exception with the specified prior exception and the cause.

ChainableIOException(ChainableIOException priorException, String message)
Constructs a new exception with the specified prior exception and a message.

ChainableIOException(ChainableIOException priorException, String message, IOException cause)
Constructs a new exception with the specified prior exception, a message and a cause.

Method Summary

Object	clone() Returns a shallow clone of this exception.
int	getAppearance()
static int	getMaxPrintExceptions()
ChainableIOException	getPrior()
int	getPriority() Returns the priority for this class of exception.
Throwable	initCause(IOException cause)
Throwable	initCause(Throwable cause) Calls initCause((IOException) cause).
void	printStackTrace(PrintStream s) Prints up to getMaxPrintExceptions() exceptions in this chain to the provided PrintStream.
void	printStackTrace(PrintStream s, int maxExceptions) Prints up to maxExceptions() exceptions in this chain to the provided PrintStream.
void	printStackTrace(PrintWriter s) Prints up to getMaxPrintExceptions() exceptions in this chain to the provided PrintStream.
void	printStackTrace(PrintWriter s, int maxExceptions) Prints up to maxExceptions() exceptions in this chain to the provided PrintStream.
static void	setMaxPrintExceptions(int maxPrintExcepions)
ChainableIOException	sortAppearance() Sorts the elements of this exception chain in descending order of their appearance.
ChainableIOException	sortPriority() Sorts the elements of this exception chain in descending order of their priority.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

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

Method Detail

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.

initCause

public final Throwable initCause(Throwable cause)

Calls initCause((IOException) cause).

Overrides:

initCause in class Throwable

Throws:

ClassCastException - If cause is not an instance of IOException.

initCause

public Throwable initCause(IOException cause)

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.

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)