net.sf.zig_project.gpl.common
Class UnexpectedException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.lang.RuntimeException
              net.sf.zig_project.gpl.common.UnexpectedException

All Implemented Interfaces:

Serializable

public class UnexpectedException

extends RuntimeException

An UnexpectedException allows rethrowing of a mandated exception where it could not otherwise be rethrown. For example:

 public long toLong(byte[] b) {
	if (b.length!=8) throw new IllegalArgumentException();
	DataInput in=new DataInputStream(new ByteArrayInputStream(b));
	try {
		return in.readLong();
	} catch (IOException e) {
		throw new UnexpectedException(e);}}
 

In this example, the compiler requires that the IOException potentially thrown by DataInput.readLong() must be caught. However, since the underlying input stream is just a memory array, and contains enough information, the Exception can never logically be thrown. Wrapping it as an UnexpectedException allows it to be rethrown, and generates the appropriate warning at runtime if our logic were mislead.

Java 1.4 introduced an Exception constructor in RuntimeException.RuntimeException(Throwable). This mechanism could be used in place of UnexpectedException where supported. However, UnexpectedException provides backward compatability with the numerous older VMs still in existance. Yet, it also features VM discovery, and on 1.4 VMs, an instance of UnexpectedException will behave just as a RuntimeException constructed by another, and will still display the underlying exception as the cause.

Version:

September 22, 2004

Author:

Frank Ziglar

See Also:

Serialized Form

Field Summary

static boolean

CAUSE_ALLOWED Determines if the superclass allows setting the cause of an exception.

Constructor Summary

UnexpectedException(Exception e)
Constructs an UnexpectedException.

Method Summary

Exception	getException() Retrieves the causing exception encapsulated as an unexpected exception.
String	toString()

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

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

Field Detail

CAUSE_ALLOWED

public static final boolean CAUSE_ALLOWED

Determines if the superclass allows setting the cause of an exception. This will generally be true on VM versions >= 1.4, and false otherwise.

See Also:

Throwable.initCause(Throwable)

Constructor Detail

UnexpectedException

public UnexpectedException(Exception e)

Constructs an UnexpectedException. Once this is called, it is immediately ready to be thrown.

Parameters:

e - the cause of the Exception

Method Detail

toString

public String toString()

getException

public Exception getException()

Retrieves the causing exception encapsulated as an unexpected exception.

Returns:

the cause