ParsingException


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  package nu.xom;
23  
24  /**
25   * <p>
26   *  The generic superclass for all the
27   *  checked exceptions thrown in XOM. The general
28   *  principle followed is that anything that could
29   *  plausibly 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 problems may not all be detected during testing.
35   * </p>
36   * 
37   * @author Elliotte Rusty Harold
38   * @version 1.0
39   *
40   */
41  public class ParsingException extends Exception   {
42  
43      
44      private Throwable   cause;
45      private int lineNumber = -1;
46      private int columnNumber = -1;
47      private String   uri;
48  
49      
50      /**
51       * <p>
52       * Creates a new <code>ParsingException</code> with a detail message
53       * and an underlying root cause.
54       * </p>
55       * 
56       * @param message a string indicating the specific problem
57       * @param cause the original cause of this exception
58       */
59      public ParsingException(String   message, Throwable   cause) {
60          super(message);
61          this.initCause(cause);
62      }
63  
64      
65      /**
66       * <p>
67       * Creates a new <code>ParsingException</code> with a detail message
68       * and an underlying root cause.
69       * </p>
70       * 
71       * @param message a string indicating the specific problem
72       * @param uri the URI of the document that caused this exception
73       * @param cause the original cause of this exception
74       */
75      public ParsingException(String   message, String   uri, Throwable   cause) {
76          super(message);
77          this.uri = uri;
78          this.initCause(cause);
79      }
80  
81      
82      /**
83       * <p>
84       * Creates a new <code>ParsingException</code> with a detail message
85       * and line and column numbers.
86       * </p>
87       * 
88       * @param message a string indicating the specific problem
89       * @param lineNumber the approximate line number 
90       *     where the problem occurs
91       * @param columnNumber the approximate column number 
92       *     where the problem occurs
93       */
94      public ParsingException(String   message, 
95        int lineNumber, int columnNumber) {
96          this(message, null, lineNumber, columnNumber, null);
97      }
98  
99      
100     /**
101      * <p>
102      * Creates a new <code>ParsingException</code> with a detail message
103      * and line and column numbers.
104      * </p>
105      * 
106      * @param message a string indicating the specific problem
107      * @param uri the URI of the document that caused this exception
108      * @param lineNumber the approximate line number 
109      *     where the problem occurs
110      * @param columnNumber the approximate column number 
111      *     where the problem occurs
112      */
113     public ParsingException(String   message, String   uri, 
114       int lineNumber, int columnNumber) {
115         this(message, uri, lineNumber, columnNumber, null);
116     }
117 
118     
119     /**
120      * <p>
121      * Creates a new <code>ParsingException</code> with a detail 
122      * message, line and column numbers, and an underlying exception.
123      * </p>
124      * 
125      * @param message a string indicating the specific problem
126      * @param uri the URI of the document that caused this exception
127      * @param lineNumber the approximate line number 
128      *     where the problem occurs
129      * @param columnNumber the approximate column number 
130      *     where the problem occurs
131      * @param cause the original cause of this exception
132      */
133     public ParsingException(String   message, String   uri, int lineNumber,
134       int columnNumber, Throwable   cause) {
135         super(message);
136         this.lineNumber = lineNumber;
137         this.columnNumber = columnNumber;
138         this.uri = uri;
139         this.initCause(cause);
140     }
141 
142     
143     /**
144      * <p>
145      * Creates a new <code>ParsingException</code> with a detail 
146      * message, line and column numbers, and an underlying exception.
147      * </p>
148      * 
149      * @param message a string indicating the specific problem
150      * @param lineNumber the approximate line number 
151      *     where the problem occurs
152      * @param columnNumber the approximate column number 
153      *     where the problem occurs
154      * @param cause the original cause of this exception
155      */
156     public ParsingException(String   message, int lineNumber,
157       int columnNumber, Throwable   cause) {
158         super(message);
159         this.lineNumber = lineNumber;
160         this.columnNumber = columnNumber;
161         this.initCause(cause);
162     }
163 
164     
165     /**
166      * <p>
167      * Creates a new <code>ParsingException</code> with a detail message.
168      * </p>
169      * 
170      * @param message a string indicating the specific problem
171      */
172     public ParsingException(String   message) {
173         super(message);
174     }
175     
176     
177     /**
178      * <p>
179      * Returns the approximate row number of the construct that
180      * caused this exception. If the row number is not known,
181      * -1 is returned.
182      * </p>
183      * 
184      * @return row number where the exception occurred
185      */
186     public int getLineNumber() {
187         return this.lineNumber;  
188     }
189 
190     /**
191      * <p>
192      * Returns the approximate column number of the construct that
193      * caused this exception. If the column number is not known,
194      * -1 is returned.
195      * </p>
196      * 
197      * @return column number where the exception occurred
198      */
199     public int getColumnNumber() {
200         return this.columnNumber;  
201     }
202 
203 
204     /**
205      * <p>
206      * Returns the system ID (generally a URL) of the document that
207      * caused this exception. If this is not known, for instance 
208      * because the document was parsed from a raw input stream or from
209      * a string, it returns null. 
210      * </p>
211      * 
212      * @return the URI of the document that caused this exception
213      */
214     public String   getURI() {
215         return this.uri;  
216     }
217 
218 
219     // null is insufficient for determining unset cause.
220     // The cause may be set to null which may not then be reset.
221     private boolean causeSet = false;
222 
223     /**
224      * <p>
225      * Sets the root cause of this exception. This may 
226      * only be called once. Subsequent calls throw an 
227      * <code>IllegalStateException</code>.
228      * </p>
229      * 
230      * <p>
231      * This method is unnecessary in Java 1.4 where it could easily be
232      * inherited from the superclass. However, including it here
233      * allows this  method to be used in Java 1.3 and earlier.
234      * </p>
235      *
236      * @param cause the root cause of this exception
237      * 
238      * @return this <code>XMLException</code>
239      * 
240      * @throws IllegalArgumentException if the cause is this exception
241      *   (An exception cannot be its own cause.)
242      * @throws IllegalStateException if this method is called twice
243      */
244     public Throwable   initCause(Throwable   cause) {
245         
246         if (causeSet) {
247             throw new IllegalStateException  ("Can't overwrite cause");
248         } 
249         else if (cause == this) {
250             throw new IllegalArgumentException  ("Self-causation not permitted"); 
251         }
252         else this.cause = cause;
253         causeSet = true;
254         return this;
255         
256     }
257 
258     
259     /**
260      * <p>
261      * Returns the underlying exception that caused this exception.
262      * </p>
263      * 
264      * @return the root exception that caused this exception 
265      *     to be thrown
266      */
267     public Throwable   getCause() {
268         return this.cause;  
269     }
270 
271     
272     /**
273      * <p>
274      * Returns a string suitable for display to the developer
275      * summarizing what went wrong where.
276      * </p>
277      * 
278      * @return an exception message suitable for display to a developer
279      */
280     public String   toString() {
281         return super.toString() + " at line " 
282           + lineNumber + ", column " + columnNumber + ".";    
283     }
284 
285     
286 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags