Class Exceptions


  • public class Exceptions
    extends java.lang.Object
    Utilities for Exceptions.
    Author:
    tomyeh
    • Constructor Summary

      Constructors 
      Constructor Description
      Exceptions()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.Throwable findCause​(java.lang.Throwable ex, java.lang.Class<?> cause)
      Finds the causes of an exception, ex, to see whether any of them is the given type.
      static java.lang.StringBuffer formatStackTrace​(java.lang.StringBuffer sb, java.lang.Throwable t, java.lang.String prefix)
      Formats the stack trace and appends it to the specified string buffer.
      static java.lang.StringBuffer formatStackTrace​(java.lang.StringBuffer sb, java.lang.Throwable t, java.lang.String prefix, int maxcnt)
      Formats the stack trace and appends it to the specified string buffer, but only display at most maxcnt lines.
      static java.lang.String formatStackTrace​(java.lang.Throwable t, java.lang.String prefix)
      Formats the stack trace and returns the result.
      static java.lang.String getBriefStackTrace​(java.lang.Throwable t)
      Returns the first few lines of the stack trace.
      static java.lang.Throwable getCause​(java.lang.Throwable ex)
      Returns the cause of the given throwable.
      static java.lang.String getExtraMessage​(java.lang.Throwable ex)
      Returns the extra message, or null if no extra.
      static java.lang.String getMessage​(int code)
      Gets the message for an exception without format-argument.
      static java.lang.String getMessage​(int code, java.lang.Object fmtArg)
      Gets the message for an exception with one format-argument.
      static java.lang.String getMessage​(int code, java.lang.Object[] fmtArgs)
      Gets the message for an exception's getMessage method.
      static java.lang.String getMessage​(java.lang.Throwable ex)
      Returns a message of the exception.
      static java.lang.Throwable getRealCause​(java.lang.Throwable ex)
      Unveils the real cause.
      static java.lang.Throwable unwrap​(java.lang.Throwable ex)
      Unwraps an exception if the enclosing one is InvocationTargetException or UndeclaredThrowableException.
      static java.lang.Throwable wrap​(java.lang.Throwable ex, java.lang.Class<? extends java.lang.Throwable> targetExceptCls)
      Converts an exception to the specified class.
      static java.lang.Throwable wrap​(java.lang.Throwable ex, java.lang.Class<? extends java.lang.Throwable> targetExceptCls, int code)
      Converts an exception to the specified class plus a message.
      static java.lang.Throwable wrap​(java.lang.Throwable ex, java.lang.Class<? extends java.lang.Throwable> targetExceptCls, int code, java.lang.Object fmtArg)
      Converts an exception to the specified class plus a message.
      static java.lang.Throwable wrap​(java.lang.Throwable ex, java.lang.Class<? extends java.lang.Throwable> targetExceptCls, int code, java.lang.Object[] fmtArgs)
      Converts an exception to the specified class plus a message.
      static java.lang.Throwable wrap​(java.lang.Throwable ex, java.lang.Class<? extends java.lang.Throwable> targetExceptCls, java.lang.String msg)
      Converts an exception to the specified class plus a message.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Exceptions

        public Exceptions()
    • Method Detail

      • findCause

        public static final java.lang.Throwable findCause​(java.lang.Throwable ex,
                                                          java.lang.Class<?> cause)
        Finds the causes of an exception, ex, to see whether any of them is the given type.
        Returns:
        the cause if found; null if not found
      • getCause

        public static final java.lang.Throwable getCause​(java.lang.Throwable ex)
        Returns the cause of the given throwable. It is the same as t.getCause, but it solves the compatibility of J2EE that might not support JDK 1.4.
      • getRealCause

        public static final java.lang.Throwable getRealCause​(java.lang.Throwable ex)
        Unveils the real cause. A throwable object is called a real cause, if it doesn't have any cause (or called chained throwable).
        Parameters:
        ex - the throwable
        Returns:
        the real cause; ex itself if it is already the real cause
        See Also:
        wrap(java.lang.Throwable, java.lang.Class<? extends java.lang.Throwable>)
      • wrap

        public static final java.lang.Throwable wrap​(java.lang.Throwable ex,
                                                     java.lang.Class<? extends java.lang.Throwable> targetExceptCls)
        Converts an exception to the specified class. If any of causes is the specified class, the cause is returned. If the giving exception is RuntimeException or error, it is re-thrown directly. In other words, Unlike findCause(java.lang.Throwable, java.lang.Class<?>), it is designed to be used in the throw statement as follows.

        Usage 1: one kind of exception is examined.

        
         try {
           ...
         } catch (Exception ex) {
           throw (MyException)Exceptions.wrap(ex, MyException.class);
         }

        Usage 2: two kinds of exceptions are examined.

        
         try {
           ...
         } catch (Exception ex) {
           Throwable t = Exceptions.findCause(ex, AnotherException.class);
           if (t != null)
              throw (AnotherException)t;
           throw (MyException)Exceptions.wrap(ex, MyException.class);
         }

        Usage 3: two kinds of exceptions are examined.

        
         try {
           ...
         } catch (AnotherException ex) {
           throw ex;
         } catch (Exception ex) {
           throw (MyException)Exceptions.wrap(ex, MyException.class);
         }

        If you already know the exception, you don't need this method -- AnotherException won't never be RuntimeException or MyException.

        
         try {
           ...
         } catch (AnotherException ex) {
           throw new MyException(ex);
         }

        Note: It assumes the exception has the constructor: MyException(Throwable cause);

        Parameters:
        targetExceptCls - the class of exception to be converted to
        ex - the exception being caught (and to be converted)
        See Also:
        getRealCause(java.lang.Throwable), SystemException.Aide.wrap(java.lang.Throwable)
      • wrap

        public static final java.lang.Throwable wrap​(java.lang.Throwable ex,
                                                     java.lang.Class<? extends java.lang.Throwable> targetExceptCls,
                                                     java.lang.String msg)
        Converts an exception to the specified class plus a message. It is similar to wrap(Throwable, Class) but with an additional message. Thus, the target exception class must has the constructor: MyException(String msg, Throwable cause);
      • wrap

        public static final java.lang.Throwable wrap​(java.lang.Throwable ex,
                                                     java.lang.Class<? extends java.lang.Throwable> targetExceptCls,
                                                     int code,
                                                     java.lang.Object[] fmtArgs)
        Converts an exception to the specified class plus a message. It is similar to wrap(Throwable, Class) but with an additional message code. Thus, the target exception class must has the constructor: MyException(int code, Object[] fmtArgs, Throwable cause);
      • wrap

        public static final java.lang.Throwable wrap​(java.lang.Throwable ex,
                                                     java.lang.Class<? extends java.lang.Throwable> targetExceptCls,
                                                     int code,
                                                     java.lang.Object fmtArg)
        Converts an exception to the specified class plus a message. It is similar to wrap(Throwable, Class) but with an additional message code. Thus, the target exception class must has the constructor: MyException(int code, Object fmtArgs, Throwable cause);
      • wrap

        public static final java.lang.Throwable wrap​(java.lang.Throwable ex,
                                                     java.lang.Class<? extends java.lang.Throwable> targetExceptCls,
                                                     int code)
        Converts an exception to the specified class plus a message. It is similar to wrap(Throwable, Class) but with an additional message code. Thus, the target exception class must has the constructor: MyException(int code, Throwable cause);
      • unwrap

        public static final java.lang.Throwable unwrap​(java.lang.Throwable ex)
        Unwraps an exception if the enclosing one is InvocationTargetException or UndeclaredThrowableException.

        Use it if you are catching exceptions thrown by Method.invoke().

      • getExtraMessage

        public static final java.lang.String getExtraMessage​(java.lang.Throwable ex)
        Returns the extra message, or null if no extra.

        Currently, it handles only SQLException

      • getMessage

        public static final java.lang.String getMessage​(java.lang.Throwable ex)
        Returns a message of the exception.
      • getMessage

        public static final java.lang.String getMessage​(int code,
                                                        java.lang.Object[] fmtArgs)
        Gets the message for an exception's getMessage method.

        It actually delegates to Messages, and then appends an error code.

      • getMessage

        public static final java.lang.String getMessage​(int code,
                                                        java.lang.Object fmtArg)
        Gets the message for an exception with one format-argument.
      • getMessage

        public static final java.lang.String getMessage​(int code)
        Gets the message for an exception without format-argument.
      • getBriefStackTrace

        public static final java.lang.String getBriefStackTrace​(java.lang.Throwable t)
        Returns the first few lines of the stack trace. It is useful to make the cause exception's stack trace to be part of the message of the exception thrown to the user.
      • formatStackTrace

        public static final java.lang.String formatStackTrace​(java.lang.Throwable t,
                                                              java.lang.String prefix)
        Formats the stack trace and returns the result. Currently, it only adds the prefix to each line.
        Parameters:
        prefix - the prefix shown in front of each line of the stack trace; null to denote empty
      • formatStackTrace

        public static final java.lang.StringBuffer formatStackTrace​(java.lang.StringBuffer sb,
                                                                    java.lang.Throwable t,
                                                                    java.lang.String prefix)
        Formats the stack trace and appends it to the specified string buffer.
        Parameters:
        sb - the string buffer to append the stack trace. A string buffer will be created if null.
        prefix - the prefix shown in front of each line of the stack trace; null to denote empty
      • formatStackTrace

        public static final java.lang.StringBuffer formatStackTrace​(java.lang.StringBuffer sb,
                                                                    java.lang.Throwable t,
                                                                    java.lang.String prefix,
                                                                    int maxcnt)
        Formats the stack trace and appends it to the specified string buffer, but only display at most maxcnt lines.

        The maximal allowed number of lines is controlled by maxcnt. Note: a stack frame is not counted, if it belongs to java.*, javax.* or sun.*.

        Parameters:
        sb - the string buffer to append the stack trace. A string buffer will be created if null.
        prefix - the prefix shown in front of each line of the stack trace; null to denote empty
        maxcnt - the maximal allowed number of lines to dump (<=0: no limit)