ptolemy.kernel.util
Class KernelException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          ptolemy.kernel.util.KernelException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

GraphTransformationException, IllegalActionException, MalformedStringException, NameDuplicationException, NoSuchItemException, TransformationException, TypeConflictException, ValidationException

public class KernelException
extends java.lang.Exception

Base class for Ptolemy exceptions. This class extends the basic JavaException with a constructor that can take a Nameable as an argument. (Note however, that it is better to use a class derived from KernelException than it is to throw a KernelException directly.)

JDK1.4 and later support exception chaining. We are implementing a version of exception chaining here ourselves so that we can use JVMs earlier than JDK1.4.

In this implementation, we have the following differences from the JDK1.4 exception chaining implementation:

In this implementation, the detail message includes the detail message from the cause argument.

In this implementation, we implement a protected _setCause() method, but not the public initCause() method that JDK1.4 has

Since:

Ptolemy II 0.2

Version:

$Id: KernelException.java 59152 2010-09-21 04:04:01Z cxh $

Author:

John S. Davis, II, Edward A. Lee, Christopher Hylands

See Also:

KernelRuntimeException, Serialized Form

Accepted Rating:

Green (cxh)

Proposed Rating:

Green (cxh)

Field Summary

private java.lang.Throwable	_cause
private java.lang.String	_message
private Nameable	_object1
private Nameable	_object2

Constructor Summary

KernelException()
Construct an exception with a no specific detail message.

KernelException(Nameable object1, Nameable object2, java.lang.String detail)
Construct an exception with a detail message that includes the names of the first two arguments plus the third argument string.

KernelException(Nameable object1, Nameable object2, java.lang.Throwable cause, java.lang.String detail)
Construct an exception with a detail message that includes the names of the first two arguments plus the third argument string.

Method Summary

protected void	_setCause(java.lang.Throwable cause) Set the cause to the specified throwable.
protected void	_setMessage(java.lang.String message) Sets the error message to the specified string.
static java.lang.String	generateMessage(java.util.Collection objects, java.lang.Throwable cause, java.lang.String detail) Generate a properly formatted exception message where the origin of the error is a collection.
static java.lang.String	generateMessage(Nameable object1, Nameable object2, java.lang.Throwable cause, java.lang.String detail) Generate a properly formatted exception message.
static java.lang.String	generateMessage(java.lang.String whereString, java.lang.Throwable cause, java.lang.String detail) Generate a properly formatted detail message.
java.lang.Throwable	getCause() Get the cause of this exception.
static java.lang.String	getFullName(Nameable object) Get the name of a Nameable object.
java.lang.String	getMessage() Get the message of this exception.
static java.lang.String	getName(Nameable object) Get the name of a Nameable object.
Nameable	getNameable1() Get the first Nameable, if any, that was passed as an argument.
Nameable	getNameable2() Get the second Nameable, if any, that was passed as an argument.
void	printStackTrace() Print a stack trace message to stderr including this exception, its stack trace and if the cause exception is known, print the cause exception and the cause stacktrace.
void	printStackTrace(java.io.PrintStream printStream) Print a stack trace message to printStream including this exception, its stack trace and if the cause exception is known, print the cause exception and the cause stacktrace.
void	printStackTrace(java.io.PrintWriter printWriter) Print a stack trace message to printWriter including this exception, its stack trace and if the cause exception is known, print the cause exception and the cause stacktrace.
static java.lang.String	stackTraceToString(java.lang.Throwable throwable) Return the stack trace of the given argument as a String.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getStackTrace, initCause, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Field Detail

_message

private java.lang.String _message

_object1

private transient Nameable _object1

_object2

private transient Nameable _object2

_cause

private java.lang.Throwable _cause

Constructor Detail

KernelException

public KernelException()

Construct an exception with a no specific detail message.

KernelException

public KernelException(Nameable object1,
                       Nameable object2,
                       java.lang.String detail)

Construct an exception with a detail message that includes the names of the first two arguments plus the third argument string. If one or more of the parameters are null, then the message of the exception is adjusted accordingly.

Parameters:

object1 - The first object.

object2 - The second object.

detail - The message.

KernelException

public KernelException(Nameable object1,
                       Nameable object2,
                       java.lang.Throwable cause,
                       java.lang.String detail)

Construct an exception with a detail message that includes the names of the first two arguments plus the third argument string. If the cause argument is non-null, then the message of this exception will include the message of the cause argument. The stack trace of the cause argument is used when we print the stack trace of this exception. If one or more of the parameters are null, then the message of the exception is adjusted accordingly.

Parameters:

object1 - The first object.

object2 - The second object.

cause - The cause of this exception.

detail - The message.

Method Detail

generateMessage

public static java.lang.String generateMessage(Nameable object1,
                                               Nameable object2,
                                               java.lang.Throwable cause,
                                               java.lang.String detail)

Generate a properly formatted exception message. If one or more of the parameters are null, then the message of the exception is adjusted accordingly. In particular, if the first two arguments are non-null, then the exception message may include the full names of the first two arguments.

This method is public static so that both KernelException and KernelRuntimeException and any classes derived from those classes can use it. KernelRuntimeException must extend RuntimeException so that the java compiler will allow methods that throw KernelRuntimeException to not declare that they throw it, and KernelException cannot extend RuntimeException for the same reason.

Parameters:

object1 - The first object.

object2 - The second object.

cause - The cause of this exception.

detail - The detail message.

Returns:

A properly formatted message

generateMessage

public static java.lang.String generateMessage(java.util.Collection objects,
                                               java.lang.Throwable cause,
                                               java.lang.String detail)

Generate a properly formatted exception message where the origin of the error is a collection.

This method is public static so that both KernelException and KernelRuntimeException and any classes derived from those classes can use it. KernelRuntimeException must extend RuntimeException so that the java compiler will allow methods that throw KernelRuntimeException to not declare that they throw it, and KernelException cannot extend RuntimeException for the same reason.

Parameters:

objects - The where objects.

cause - The cause of this exception.

detail - The detail message.

Returns:

A properly formatted message

generateMessage

public static java.lang.String generateMessage(java.lang.String whereString,
                                               java.lang.Throwable cause,
                                               java.lang.String detail)

Generate a properly formatted detail message. If one or more of the parameters are null, then the message of this exception is adjusted accordingly.

This method is public static so that both KernelException and KernelRuntimeException and any classes derived from those classes can use it. KernelRuntimeException must extend RuntimeException so that the java compiler will allow methods that throw KernelRuntimeException to not declare that they throw it, and KernelException cannot extend RuntimeException for the same reason.

Parameters:

whereString - The string that identifies where the error occurred, as in for example "in object: foo".

cause - The cause of this exception.

detail - The message.

Returns:

A properly formatted message

getCause

public java.lang.Throwable getCause()

Get the cause of this exception.

Overrides:

getCause in class java.lang.Throwable

Returns:

The cause that was passed in as an argument to the constructor, or null if no cause was specified.

getFullName

public static java.lang.String getFullName(Nameable object)

Get the name of a Nameable object. This method uses getName(), concatenating what it returns for each object in the hierarchy, separated by periods. If the argument is a null reference, return an empty string. If the name of the argument or any of its containers is the empty string, then that name is replaced with "<Unnamed Object>".

This method is public static so that both KernelException and KernelRuntimeException and any classes derived from those classes can use it. KernelRuntimeException must extend RuntimeException so that the java compiler will allow methods that throw KernelRuntimeException to not declare that they throw it, and KernelException cannot extend RuntimeException for the same reason.

Parameters:

object - An object with a full name.

Returns:

The full name of the argument.

getMessage

public java.lang.String getMessage()

Get the message of this exception. The message may have been adjusted if one of the constructor arguments was null, so the value returned by this method may not necessarily equal the value of the detail argument of of the constructor.

Overrides:

getMessage in class java.lang.Throwable

Returns:

The error message.

getName

public static java.lang.String getName(Nameable object)

Get the name of a Nameable object. If the argument is a null reference, return an empty string. If the name is the empty string, then we return "<Unnamed Object>".

Parameters:

object - An object with a name.

Returns:

The name of the argument.

getNameable1

public Nameable getNameable1()

Get the first Nameable, if any, that was passed as an argument.

Returns:

The first Nameable that was passed in. If no Nameable was passed in, then return null.

getNameable2

public Nameable getNameable2()

Get the second Nameable, if any, that was passed as an argument.

Returns:

The second Nameable that was passed in. If no Nameable was passed in, then return null.

printStackTrace

public void printStackTrace()

Print a stack trace message to stderr including this exception, its stack trace and if the cause exception is known, print the cause exception and the cause stacktrace.

Overrides:

printStackTrace in class java.lang.Throwable

printStackTrace

public void printStackTrace(java.io.PrintStream printStream)

Print a stack trace message to printStream including this exception, its stack trace and if the cause exception is known, print the cause exception and the cause stacktrace.

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

printStream - The PrintStream to write to.

printStackTrace

public void printStackTrace(java.io.PrintWriter printWriter)

Print a stack trace message to printWriter including this exception, its stack trace and if the cause exception is known, print the cause exception and the cause stacktrace.

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

printWriter - The PrintWriter to write to.

stackTraceToString

public static java.lang.String stackTraceToString(java.lang.Throwable throwable)

Return the stack trace of the given argument as a String. This method is useful if we are catching and rethrowing a throwable that does not take a throwable cause argument. For example, the XML parser exception does not take a cause argument, so we call this method instead. This method should be used instead of Throwable.printStackTrace(), which prints the stack trace to stderr, which is likely to be hidden if we are running a Ptolemy application from anything but a shell console.

Parameters:

throwable - A throwable.

Returns:

The stack trace of the throwable.

_setCause

protected void _setCause(java.lang.Throwable cause)

Set the cause to the specified throwable.

Parameters:

cause - The cause of this exception

_setMessage

protected void _setMessage(java.lang.String message)

Sets the error message to the specified string. If the message argument is null, then the error message is set to the empty string.

Parameters:

message - The message.