/*
    * Copyright (c) 2001 - 2005 ivata limited.
    * All rights reserved.
    * -----------------------------------------------------------------------------
    * ivata masks may be redistributed under the GNU General Public
    * License as published by the Free Software Foundation;
    * version 2 of the License.
    *
    * These programs are free software; you can redistribute them and/or
   * modify them under the terms of the GNU General Public License
   * as published by the Free Software Foundation; version 2 of the License.
   *
   * These programs are distributed in the hope that they will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   *
   * See the GNU General Public License in the file LICENSE.txt for more
   * details.
   *
   * If you would like a copy of the GNU General Public License write to
   *
   * Free Software Foundation, Inc.
   * 59 Temple Place - Suite 330
   * Boston, MA 02111-1307, USA.
   *
   *
   * To arrange commercial support and licensing, contact ivata at
   *                  http://www.ivata.com/contact.jsp
   * -----------------------------------------------------------------------------
   * $Log: ThrowableHandling.java,v $
   * Revision 1.9  2005/10/03 21:32:22  colinmacleod
   * Cosmetic (line length) fix.
   *
   * Revision 1.8  2005/10/03 21:31:29  colinmacleod
   * Fixed the comparison order or cause properties, so that rootCause is checked
   * before cause.
   *
   * Revision 1.7  2005/10/03 10:17:25  colinmacleod
   * Fixed some style and javadoc issues.
   *
   * Revision 1.6  2005/10/02 14:06:32  colinmacleod
   * Added/improved log4j logging.
   *
   * Revision 1.5  2005/04/09 18:04:17  colinmacleod
   * Changed copyright text to GPL v2 explicitly.
   *
   * Revision 1.4  2005/01/19 12:43:00  colinmacleod
   * Fixed getCause: it was only returning the immediate cause.
   *
   * Revision 1.3  2005/01/11 10:51:02  colinmacleod
   * Added log tracing.
   *
   * Revision 1.2  2005/01/06 22:21:45  colinmacleod
   * Moved up a version number.
   * Changed copyright notices to 2005.
   * Updated the documentation:
   *   - started working on multiproject:site docu.
   *   - changed the logo.
   * Added checkstyle and fixed LOADS of style issues.
   * Added separate thirdparty subproject.
   * Added struts (in web), util and webgui (in webtheme) from ivata op.
   *
   * Revision 1.1  2004/12/31 19:17:09  colinmacleod
   * Renamed from ExceptionHandling to ThrowableHandling.
   *
   * Revision 1.1  2004/09/30 15:16:04  colinmacleod
   * Split off addressbook elements into security subproject.
   *
   * Revision 1.2  2004/03/21 21:16:19  colinmacleod
   * Shortened name to ivata op.
   *
   * Revision 1.1.1.1  2004/01/27 20:58:00  colinmacleod
   * Moved ivata op to SourceForge.
   *
   * Revision 1.2  2003/10/17 12:36:13  jano
   * fixing problems with building
   * converting intranet -> portal
   * Eclipse building
   *
   * Revision 1.1.1.1  2003/10/13 20:50:15  colin
   * Restructured portal into subprojects
   *
   * Revision 1.7  2003/02/24 19:27:31  colin
   * restructured file paths
   *
   * Revision 1.6  2003/02/04 17:43:52  colin
   * copyright notice
   *
   * Revision 1.5  2002/11/12 10:16:10  colin
   * added getRemoteException method with support for EJBException
   *
   * Revision 1.4  2002/09/16 14:18:15  colin
   * improved the error messages for embedded exceptions
   *
   * Revision 1.3  2002/09/09 13:39:55  colin
   * fixed bug in the displaying of the exception class
   *
   * Revision 1.2  2002/08/29 16:40:23  colin
   * improved documentation
  *
  * Revision 1.1  2002/06/13 11:22:21  colin
  * first version with rose model integration.
  * -----------------------------------------------------------------------------
  */
 package com.ivata.mask.util;
 import java.beans.PropertyDescriptor;
 import java.lang.reflect.InvocationTargetException;
 import org.apache.commons.beanutils.PropertyUtils;
 import org.apache.log4j.Logger;
 /***
  * <p>
  * Routines for handling exceptions.
  * </p>
  * <p>
  * Don't create an instance of this class; use the static final methods.
  * </p>
  *
  * @since ivata masks 0.4 (2002-05-20)
  * @author Colin MacLeod
  * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
  * @version $Revision: 1.9 $
  */
 public final class ThrowableHandling {
     /***
      * <p>
      * This array of string contains all the known methods which will return a
      * cause exception/throwable. The order is the order they will be searched
      * for.
      * </p>
      */
     private static final String[] CAUSE_PROPERTIES = {
                             "rootCause",
                             "targetException",
                             "undeclaredThrowable",
                             "causedBy",
                             "cause"
     };
     /***
      * <p>
      * Used to identify the preprended text in embedded exceptions.
      * </p>
      */
     static final String[] EMBEDDED = {
                         "Embedded Exception",
                         "SystemException is:"
     };
     /***
      * <copyDoc>Refer to {@link Logger}.</copyDoc>
      */
     private static final Logger logger
         = Logger.getLogger(ThrowableHandling.class);
     /***
      * <p>
      * If the parameter provided is a <code>RemoteException</code>, then
      * provide the original exception, otherwise just return this exception.
      * </p>
      *
      * @param throwable
      *            throwable object to return the original exception for.
      * @return the exception which originally was thrown.
      */
     public static Throwable getCause(final Throwable throwable) {
         if (logger.isDebugEnabled()) {
             logger.debug("getCause(Throwable throwable = " + throwable
                     + ") - start");
         }
 
         if (throwable == null) {
             if (logger.isDebugEnabled()) {
                 logger.debug("getCause(Throwable) - end - return value = "
                         + null);
             }
             return null;
         }
         Throwable returnThrowable = throwable;
         Throwable cause;
         while (((cause = getCauseOrNull(returnThrowable)) != null)
                 && (cause != returnThrowable)) {
             returnThrowable = cause;
         }
 
         if (logger.isDebugEnabled()) {
             logger.debug("getCause(Throwable) - end - return value = "
                     + returnThrowable);
         }
         return returnThrowable;
     }
     /***
      * <p>
      * If the given throwable was caused by another, get that cause.
      * </p>
      *
      * @param throwable
      *            the throwable to find the cause for
      * @return cause of this throwable, or <code>null</code> if there is no
      *         original cause.
      */
     private static Throwable getCauseOrNull(final Throwable throwable) {
         if (logger.isDebugEnabled()) {
             logger.debug("getCauseOrNull(Throwable throwable = " + throwable
                     + ") - start");
         }
 
         if (throwable == null) {
             if (logger.isDebugEnabled()) {
                 logger.debug("getCauseOrNull: throwable was null");
             }
             return null;
         }
         PropertyDescriptor[] descriptors = PropertyUtils
                 .getPropertyDescriptors(throwable.getClass());
         // find the descriptor which matches a known name
         String causeProperty = null;
         outerLoop:
         for (int j = 0; j < ThrowableHandling.CAUSE_PROPERTIES.length; j++) {
             String property = ThrowableHandling.CAUSE_PROPERTIES[j];
             for (int i = 0; i < descriptors.length; i++) {
                 PropertyDescriptor descriptor = descriptors[i];
                 if (logger.isDebugEnabled()) {
                     logger.debug("Comparing property '"
                             + descriptor.getName()
                             + "' to known cause property '"
                             + property
                             + "'");
                 }
                 if (property.equals(descriptor.getName())) {
                     if (logger.isDebugEnabled()) {
                         logger.debug("getCauseOrNull: using '"
                                 + property
                                 + "' as cause property");
                     }
                     causeProperty = property;
                     break outerLoop;
                 }
             }
         }
         // if there is no property to find the cause, there is not much we can
         // do...
         if (causeProperty == null) {
             if (logger.isDebugEnabled()) {
                 logger.debug("getCauseOrNull: cause property is null");
             }
             return null;
         }
         try {
             Throwable returnThrowable = (Throwable) PropertyUtils.getProperty(
                     throwable, causeProperty);
             if (logger.isDebugEnabled()) {
                 logger.debug("getCauseOrNull(Throwable) - end - return value = "
                                 + returnThrowable);
             }
             return returnThrowable;
         } catch (IllegalAccessException e) {
             logger.error("getCauseOrNull(Throwable)", e);
 
             if (logger.isDebugEnabled()) {
                 logger.debug(e);
             }
             return null;
         } catch (InvocationTargetException e) {
             logger.error("getCauseOrNull(Throwable)", e);
 
             if (logger.isDebugEnabled()) {
                 logger.debug(e);
             }
             return null;
         } catch (NoSuchMethodException e) {
             logger.error("getCauseOrNull(Throwable)", e);
 
             if (logger.isDebugEnabled()) {
                 logger.debug(e);
             }
             return null;
         }
     }
     /***
      * <p>
      * If the parameter provided is a <code>RemoteException</code>, then
      * provide the message from the original exception, otherwise just return
      * the message of this exception.
      * </p>
      *
      * @param throwable
      *            throwable object to return the original exception message for.
      * @return the message of the exception which originally was thrown.
      */
     public static String getRemoteMessage(final Throwable throwable) {
         if (logger.isDebugEnabled()) {
             logger.debug("getRemoteMessage(Throwable throwable = " + throwable
                     + ") - start");
         }
 
         Throwable remoteException = getCause(throwable);
         String messageText = getCause(remoteException).getMessage();
         int index, textPosition;
         // look for any embedded exception text and remove it
         if (messageText == null) {
             messageText = "An application exception occurred, "
                     + remoteException.getClass() + ".";
         } else {
             // go thro' all of the texts which signify an embedded message
             for (index = 0; index < EMBEDDED.length; ++index) {
                 if ((textPosition = messageText.indexOf(EMBEDDED[index]))
                         != -1) {
                     messageText = messageText.substring(textPosition
                             + EMBEDDED[index].length());
                     break;
                 }
             }
         }
 
         if (logger.isDebugEnabled()) {
             logger.debug("getRemoteMessage(Throwable) - end - return value = "
                     + messageText);
         }
         return messageText;
     }
     /***
      * <p>
      * Private default constructor ensures utility class functionality.
      * </p>
      */
     private ThrowableHandling() {
     }
 }