1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54 package org.jdiagnose.exception;
55
56 import java.io.PrintStream;
57 import java.io.PrintWriter;
58
59 /***
60 * An interface to be implemented by {@link java.lang.Throwable}
61 * extensions which would like to be able to nest root exceptions
62 * inside themselves.
63 *
64 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
65 * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
66 * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
67 * @author Pete Gieser
68 * @since 1.0
69 * @version $Id: Nestable.java,v 1.1 2004/06/16 09:54:35 dkfn Exp $
70 */
71 public interface Nestable {
72
73 /***
74 * Returns the reference to the exception or error that caused the
75 * exception implementing the <code>Nestable</code> to be thrown.
76 *
77 * @return throwable that caused the original exception
78 */
79 public Throwable getCause();
80
81 /***
82 * Returns the error message of this and any nested
83 * <code>Throwable</code>.
84 *
85 * @return the error message
86 */
87 public String getMessage();
88
89 /***
90 * Returns the error message of the <code>Throwable</code> in the chain
91 * of <code>Throwable</code>s at the specified index, numbered from 0.
92 *
93 * @param index the index of the <code>Throwable</code> in the chain of
94 * <code>Throwable</code>s
95 * @return the error message, or null if the <code>Throwable</code> at the
96 * specified index in the chain does not contain a message
97 * @throws IndexOutOfBoundsException if the <code>index</code> argument is
98 * negative or not less than the count of <code>Throwable</code>s in the
99 * chain
100 */
101 public String getMessage(int index);
102
103 /***
104 * Returns the error message of this and any nested <code>Throwable</code>s
105 * in an array of Strings, one element for each message. Any
106 * <code>Throwable</code> not containing a message is represented in the
107 * array by a null. This has the effect of cause the length of the returned
108 * array to be equal to the result of the {@link #getThrowableCount()}
109 * operation.
110 *
111 * @return the error messages
112 */
113 public String[] getMessages();
114
115 /***
116 * Returns the <code>Throwable</code> in the chain of
117 * <code>Throwable</code>s at the specified index, numbered from 0.
118 *
119 * @param index the index, numbered from 0, of the <code>Throwable</code> in
120 * the chain of <code>Throwable</code>s
121 * @return the <code>Throwable</code>
122 * @throws IndexOutOfBoundsException if the <code>index</code> argument is
123 * negative or not less than the count of <code>Throwable</code>s in the
124 * chain
125 */
126 public Throwable getThrowable(int index);
127
128 /***
129 * Returns the number of nested <code>Throwable</code>s represented by
130 * this <code>Nestable</code>, including this <code>Nestable</code>.
131 *
132 * @return the throwable count
133 */
134 public int getThrowableCount();
135
136 /***
137 * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
138 * in an array of <code>Throwable</code>s, one element for each
139 * <code>Throwable</code>.
140 *
141 * @return the <code>Throwable</code>s
142 */
143 public Throwable[] getThrowables();
144
145 /***
146 * Returns the index, numbered from 0, of the first occurrence of the
147 * specified type in the chain of <code>Throwable</code>s, or -1 if the
148 * specified type is not found in the chain.
149 *
150 * @param type <code>Class</code> to be found
151 * @return index of the first occurrence of the type in the chain, or -1 if
152 * the type is not found
153 */
154 public int indexOfThrowable(Class type);
155
156 /***
157 * Returns the index, numbered from 0, of the first <code>Throwable</code>
158 * that matches the specified type in the chain of <code>Throwable</code>s
159 * with an index greater than or equal to the specified index, or -1 if
160 * the type is not found.
161 *
162 * @param type <code>Class</code> to be found
163 * @param fromIndex the index, numbered from 0, of the starting position in
164 * the chain to be searched
165 * @return index of the first occurrence of the type in the chain, or -1 if
166 * the type is not found
167 * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
168 * is negative or not less than the count of <code>Throwable</code>s in the
169 * chain
170 */
171 public int indexOfThrowable(Class type, int fromIndex);
172
173 /***
174 * Prints the stack trace of this exception to the specified print
175 * writer. Includes information from the exception, if any,
176 * which caused this exception.
177 *
178 * @param out <code>PrintWriter</code> to use for output.
179 */
180 public void printStackTrace(PrintWriter out);
181
182 /***
183 * Prints the stack trace of this exception to the specified print
184 * stream. Includes information from the exception, if any,
185 * which caused this exception.
186 *
187 * @param out <code>PrintStream</code> to use for output.
188 */
189 public void printStackTrace(PrintStream out);
190
191 /***
192 * Prints the stack trace for this exception only--root cause not
193 * included--using the provided writer. Used by {@link
194 * org.jdiagnose.exception.NestableDelegate} to write
195 * individual stack traces to a buffer. The implementation of
196 * this method should call
197 * <code>super.printStackTrace(out);</code> in most cases.
198 *
199 * @param out The writer to use.
200 */
201 public void printPartialStackTrace(PrintWriter out);
202
203 }