1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang.exception;
18
19 import java.io.PrintStream;
20 import java.io.PrintWriter;
21
22 /**
23 * An interface to be implemented by {@link java.lang.Throwable}
24 * extensions which would like to be able to nest root exceptions
25 * inside themselves.
26 *
27 * @author Daniel L. Rall
28 * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
29 * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
30 * @author Pete Gieser
31 * @since 1.0
32 * @version $Id: Nestable.java 512889 2007-02-28 18:18:20Z dlr $
33 */
34 public interface Nestable {
35
36 /**
37 * Returns the reference to the exception or error that caused the
38 * exception implementing the <code>Nestable</code> to be thrown.
39 *
40 * @return throwable that caused the original exception
41 */
42 public Throwable getCause();
43
44 /**
45 * Returns the error message of this and any nested
46 * <code>Throwable</code>.
47 *
48 * @return the error message
49 */
50 public String getMessage();
51
52 /**
53 * Returns the error message of the <code>Throwable</code> in the chain
54 * of <code>Throwable</code>s at the specified index, numbered from 0.
55 *
56 * @param index the index of the <code>Throwable</code> in the chain of
57 * <code>Throwable</code>s
58 * @return the error message, or null if the <code>Throwable</code> at the
59 * specified index in the chain does not contain a message
60 * @throws IndexOutOfBoundsException if the <code>index</code> argument is
61 * negative or not less than the count of <code>Throwable</code>s in the
62 * chain
63 */
64 public String getMessage(int index);
65
66 /**
67 * Returns the error message of this and any nested <code>Throwable</code>s
68 * in an array of Strings, one element for each message. Any
69 * <code>Throwable</code> not containing a message is represented in the
70 * array by a null. This has the effect of cause the length of the returned
71 * array to be equal to the result of the {@link #getThrowableCount()}
72 * operation.
73 *
74 * @return the error messages
75 */
76 public String[] getMessages();
77
78 /**
79 * Returns the <code>Throwable</code> in the chain of
80 * <code>Throwable</code>s at the specified index, numbered from 0.
81 *
82 * @param index the index, numbered from 0, of the <code>Throwable</code> in
83 * the chain of <code>Throwable</code>s
84 * @return the <code>Throwable</code>
85 * @throws IndexOutOfBoundsException if the <code>index</code> argument is
86 * negative or not less than the count of <code>Throwable</code>s in the
87 * chain
88 */
89 public Throwable getThrowable(int index);
90
91 /**
92 * Returns the number of nested <code>Throwable</code>s represented by
93 * this <code>Nestable</code>, including this <code>Nestable</code>.
94 *
95 * @return the throwable count
96 */
97 public int getThrowableCount();
98
99 /**
100 * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
101 * in an array of <code>Throwable</code>s, one element for each
102 * <code>Throwable</code>.
103 *
104 * @return the <code>Throwable</code>s
105 */
106 public Throwable[] getThrowables();
107
108 /**
109 * Returns the index, numbered from 0, of the first occurrence of the
110 * specified type, or a subclass, in the chain of <code>Throwable</code>s.
111 * The method returns -1 if the specified type is not found in the chain.
112 * <p>
113 * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
114 * such that this method matches subclasses.
115 * If you want to NOT match subclasses, please use
116 * {@link ExceptionUtils#indexOfThrowable(Throwable, Class)}
117 * (which is avaiable in all versions of lang).
118 *
119 * @param type the type to find, subclasses match, null returns -1
120 * @return index of the first occurrence of the type in the chain, or -1 if
121 * the type is not found
122 */
123 public int indexOfThrowable(Class type);
124
125 /**
126 * Returns the index, numbered from 0, of the first <code>Throwable</code>
127 * that matches the specified type, or a subclass, in the chain of <code>Throwable</code>s
128 * with an index greater than or equal to the specified index.
129 * The method returns -1 if the specified type is not found in the chain.
130 * <p>
131 * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
132 * such that this method matches subclasses.
133 * If you want to NOT match subclasses, please use
134 * {@link ExceptionUtils#indexOfThrowable(Throwable, Class, int)}
135 * (which is avaiable in all versions of lang).
136 *
137 * @param type the type to find, subclasses match, null returns -1
138 * @param fromIndex the index, numbered from 0, of the starting position in
139 * the chain to be searched
140 * @return index of the first occurrence of the type in the chain, or -1 if
141 * the type is not found
142 * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
143 * is negative or not less than the count of <code>Throwable</code>s in the
144 * chain
145 */
146 public int indexOfThrowable(Class type, int fromIndex);
147
148 /**
149 * Prints the stack trace of this exception to the specified print
150 * writer. Includes information from the exception, if any,
151 * which caused this exception.
152 *
153 * @param out <code>PrintWriter</code> to use for output.
154 */
155 public void printStackTrace(PrintWriter out);
156
157 /**
158 * Prints the stack trace of this exception to the specified print
159 * stream. Includes information from the exception, if any,
160 * which caused this exception.
161 *
162 * @param out <code>PrintStream</code> to use for output.
163 */
164 public void printStackTrace(PrintStream out);
165
166 /**
167 * Prints the stack trace for this exception only--root cause not
168 * included--using the provided writer. Used by
169 * {@link org.apache.commons.lang.exception.NestableDelegate} to write
170 * individual stack traces to a buffer. The implementation of
171 * this method should call
172 * <code>super.printStackTrace(out);</code> in most cases.
173 *
174 * @param out The writer to use.
175 */
176 public void printPartialStackTrace(PrintWriter out);
177
178 }
Save This Page