1   /**
2    * Distribution License:
3    * JSword is free software; you can redistribute it and/or modify it under
4    * the terms of the GNU Lesser General Public License, version 2.1 or later
5    * as published by the Free Software Foundation. This program is distributed
6    * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
7    * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
8    * See the GNU Lesser General Public License for more details.
9    *
10   * The License is available on the internet at:
11   *      http://www.gnu.org/copyleft/lgpl.html
12   * or by writing to:
13   *      Free Software Foundation, Inc.
14   *      59 Temple Place - Suite 330
15   *      Boston, MA 02111-1307, USA
16   *
17   * © CrossWire Bible Society, 2005 - 2016
18   *
19   */
20  package org.crosswire.common.util;
21  
22  import org.crosswire.jsword.JSMsg;
23  
24  
25  /**
26   * A LucidException adds 2 concepts to a base Exception, that of a wrapped
27   * Exception, that of internationalized (i18n) messages.
28   * 
29   * <p>
30   * The first addition is the concept of an optional wrapped Exception (actually
31   * a Throwable), which describes what caused this to happen. Any well defined
32   * interface will define the exact exceptions that the methods of that interface
33   * will throw, and not leave it to the ambiguous "throws Exception". However the
34   * interface should have no idea how it will be implemented and so the details
35   * of exactly what broke under the covers gets lost. With LucidException this
36   * detail is kept in the wrapped Exception. This functionality has been added to
37   * the base Exception class in J2SE 1.4
38   * </p>
39   * 
40   * <p>
41   * The second addition is the concept of i18n messages. Normal Exceptions are
42   * created with an almost random string in the message field, LucidExceptions
43   * define this string to be a key into a resource bundle, and to help formatting
44   * this string there is an optional Object array of format options. There is a
45   * constructor that allows us to specify no i18n lookup, which is useful if this
46   * lookup may have been done already.
47   * </p>
48   * 
49   * @see gnu.lgpl.License The GNU Lesser General Public License for details.
50   * @author Joe Walker
51   * @see LucidRuntimeException
52   */
53  public class LucidException extends Exception {
54      /**
55       * All LucidExceptions are constructed with references to resources in an
56       * i18n properties file.
57       * 
58       * @param msg
59       *            The resource id to read
60       */
61      public LucidException(String msg) {
62          super(msg);
63      }
64  
65      /**
66       * All LucidExceptions are constructed with references to resources in an
67       * i18n properties file.
68       * 
69       * @param msg   The resource id to read
70       * @param cause The cause of the exception
71       */
72      public LucidException(String msg, Throwable cause) {
73          super(msg, cause);
74      }
75  
76      /**
77       * Accessor of the full detailed version of the string
78       * 
79       * @return The full unraveled i18n string
80       */
81      public String getDetailedMessage() {
82          Throwable cause = getCause();
83          if (cause == null) {
84              return getMessage();
85          }
86  
87          // TRANSLATOR: When an error occurs this label precedes the details of the problem.
88          String reason = JSMsg.gettext("Reason:");
89          if (cause instanceof LucidException) {
90              LucidException lex = (LucidException) cause;
91              return getMessage() + reason + lex.getDetailedMessage();
92          }
93          return getMessage() + reason + cause.getMessage();
94      }
95  
96      /**
97       * Serialization ID
98       */
99      private static final long serialVersionUID = 3257846580311963191L;
100 }
101