XIncludeException


1   /* Copyright 2002-2005 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.xinclude;
23  
24  /**
25   * <p>
26   * The generic superclass for all checked exceptions that may be thrown 
27   * as a result of a violation of XInclude's rules.
28   * </p>
29   * 
30   * @author Elliotte Rusty Harold
31   * @version 1.0
32   */
33  public class XIncludeException extends Exception   {
34  
35      
36      private String   uri;
37  
38      /**
39       * <p>
40       * Constructs an <code>XIncludeException</code> with the specified
41       * detail message.
42       * </p>
43       * 
44       * @param message a string indicating the specific problem
45       */
46      public XIncludeException(String   message) {
47          super(message);
48      }
49  
50      
51      /**
52       * <p>
53       * Constructs an <code>XIncludeException</code> with the specified 
54       * detail message and initial cause. The error message string 
55       * <code>message</code> can later be retrieved by the 
56       * <code>{@link java.lang.Throwable#getMessage}</code>
57       * method of class <code>java.lang.Throwable</code>.
58       * </p>
59       * 
60       * @param message a string indicating the specific problem
61       * @param cause   the initial cause of the exception
62       */
63      public XIncludeException(String   message, Throwable   cause) {
64          super(message);
65          initCause(cause);
66      }
67  
68      
69      /**
70       * <p>
71       * Creates a new <code>XIncludeException</code> with a detail 
72       * message, line and column numbers, and the URI of the document
73       * that caused the exception.
74       * </p>
75       * 
76       * @param message a string indicating the specific problem
77       * @param uri the URI of the document that caused this exception
78       */
79      public XIncludeException(String   message, String   uri) {
80          super(message);
81          this.uri = uri;
82      }
83  
84      
85      /**
86       * <p>
87       * Returns the URI of the document that caused this exception. 
88       * If the URI is not known, null is returned.
89       * </p>
90       * 
91       * @return URI of the document where the exception occurred
92       */
93      public String   getURI() {
94          return this.uri;  
95      }
96  
97      
98      private Throwable   cause;
99  
100     
101     /**
102      * <p>
103      * When an <code>IOException</code>,  
104      * <code>MalformedURLException</code>, or other generic  
105      * exception is thrown while processing an XML document
106      * for XIncludes, it is customarily replaced
107      * by some form of <code>XIncludeException</code>.  
108      * This method allows you to retrieve the original exception.
109      * It returns null if no such exception caused this 
110      * <code>XIncludeException</code>.
111      *</p>
112      * 
113      * @return the underlying exception which 
114      *     caused this XIncludeException to be thrown
115      */
116     public Throwable   getCause() {
117         return this.cause;  
118     }
119 
120     
121     // null is insufficient for detecting an uninitialized cause.
122     // The cause may be set to null which may not then be reset.
123     private boolean causeSet = false;
124 
125     
126     /**
127      * <p>
128      * When an <code>IOException</code>,  
129      * <code>MalformedURLException</code>, or other generic exception 
130      * is thrown while processing an XML document
131      * for XIncludes, it is customarily replaced
132      * by some form of <code>XIncludeException</code>.  
133      * This method allows you to store the original exception.
134      * </p>
135      *
136      * @param cause the root cause of this exception
137      * 
138      * @return this <code>XIncludeException</code>
139      * 
140      * @throws IllegalArgumentException if the cause is this exception
141      *   (An exception cannot be its own cause.)
142      * @throws IllegalStateException if this method is called twice
143      */
144     public Throwable   initCause(Throwable   cause) {
145         if (causeSet) {
146             throw new IllegalStateException  ("Can't overwrite cause");
147         } 
148         else if (cause == this) {
149             throw new IllegalArgumentException  ("Self-causation not permitted"); 
150         }
151         else this.cause = cause;
152         causeSet = true;
153         return this;
154     }
155 
156     
157 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags