Package ptolemy.kernel.util

Class 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$
    Author:
    John S. Davis, II, Edward A. Lee, Christopher Hylands
    See Also:
    KernelRuntimeException, Serialized Form
    Pt.AcceptedRating:
    Green (cxh)
    Pt.ProposedRating:
    Green (cxh)

    • Constructor Summary

      Constructors 
      Constructor Description
      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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.lang.String whereString, java.lang.Throwable cause, java.lang.String detail)
      Generate a properly formatted detail message.
      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.
      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

        addSuppressed, fillInStackTrace, getLocalizedMessage, getStackTrace, getSuppressed, initCause, setStackTrace, toString

      • Methods inherited from class java.lang.Object

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

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