XMLException


1   /* Copyright 2002-2004 Elliotte Rusty Harold
2      
3      This library is free software; you can redistribute it and/or modify
4      it under the terms of version 2.1 of the GNU Lesser General Public 
5      License as published by the Free Software Foundation.
6      
7      This library is distributed in the hope that it will be useful,
8      but WITHOUT ANY WARRANTY; without even the implied warranty of
9      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
10     GNU Lesser General Public License for more details.
11     
12     You should have received a copy of the GNU Lesser General Public
13     License along with this library; if not, write to the 
14     Free Software Foundation, Inc., 59 Temple Place, Suite 330, 
15     Boston, MA 02111-1307  USA
16     
17     You can contact Elliotte Rusty Harold by sending e-mail to
18     elharo@metalab.unc.edu. Please include the word "XOM" in the
19     subject line. The XOM home page is located at http://www.xom.nu/
20  */
21  
22  
23  package nu.xom;
24  
25  /**
26   * <p>
27   *  The generic superclass for most runtime exceptions thrown in 
28   *  <code>nu.xom</code>. The general principle followed is that 
29   *  anything that can normally be detected by testing such as 
30   *  using spaces in an element name is a runtime exception.
31   *  Exceptions that depend on environmental conditions,
32   *  such as might occur when parsing an external file,
33   *  are checked exceptions, because these depend on variable input,
34   *  and thus all problems may not be detected during testing.
35   * </p>
36   * 
37   * @author Elliotte Rusty Harold
38   * @version 1.0
39   *
40   */
41  public class XMLException extends RuntimeException   {
42  
43      private Throwable   cause;
44  
45      
46      /**
47       * <p>
48       * Creates a new <code>XMLException</code> 
49       * with the specified detail message
50       * and an underlying root cause.
51       * </p>
52       *
53       * @param message information about the cause of the exception
54       * @param cause the nested exception that caused this exception
55       */
56      public XMLException(String   message, Throwable   cause) {
57          super(message);
58          this.initCause(cause);
59      }
60      
61      
62      /**
63       * <p>
64       *   Creates a new <code>XMLException</code> with 
65       *   the specified detail message.
66       *  </p>
67       *
68       * @param message information about the cause of the exception
69       */
70      public XMLException(String   message) {
71          super(message);
72      }
73      
74      
75      /**
76       * <p>
77       *  Return the original cause that led to this exception,
78       *  or null if there was no original exception.
79       * </p>
80       *
81       * @return the root cause of this exception
82       */
83      public Throwable   getCause() {
84          return this.cause;  
85      }
86  
87      
88      // null is insufficient for detecting an uninitialized cause.
89      // The cause may be set to null which may not then be reset.
90      private boolean causeSet = false;
91  
92      
93      /**
94       * <p>
95       * Sets the root cause of this exception. This may 
96       * only be called once. Subsequent calls throw an 
97       * <code>IllegalStateException</code>.
98       * </p>
99       * 
100      * <p>
101      * This method is unnecessary in Java 1.4 where it could easily be
102      * inherited from the superclass. However, including it here
103      * allows this  method to be used in Java 1.3 and earlier.
104      * </p>
105      *
106      * @param cause the root cause of this exception
107      * 
108      * @return this <code>XMLException</code>
109      * 
110      * @throws IllegalArgumentException if the cause is this exception
111      *   (An exception cannot be its own cause.)
112      * @throws IllegalStateException if this method is called twice
113      */
114     public Throwable   initCause(Throwable   cause) {
115         
116         if (causeSet) {
117             throw new IllegalStateException  ("Can't overwrite cause");
118         } 
119         else if (cause == this) {
120             throw new IllegalArgumentException  ("Self-causation not permitted"); 
121         }
122         else this.cause = cause;
123         causeSet = true;
124         return this;
125         
126     }
127 
128     
129 }
130
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags