001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.lang.exception;
018
019 import java.io.PrintStream;
020 import java.io.PrintWriter;
021
022 /**
023 * An interface to be implemented by {@link java.lang.Throwable}
024 * extensions which would like to be able to nest root exceptions
025 * inside themselves.
026 *
027 * @author Daniel L. Rall
028 * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
029 * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
030 * @author Pete Gieser
031 * @since 1.0
032 * @version $Id: Nestable.java 512889 2007-02-28 18:18:20Z dlr $
033 */
034 public interface Nestable {
035
036 /**
037 * Returns the reference to the exception or error that caused the
038 * exception implementing the <code>Nestable</code> to be thrown.
039 *
040 * @return throwable that caused the original exception
041 */
042 public Throwable getCause();
043
044 /**
045 * Returns the error message of this and any nested
046 * <code>Throwable</code>.
047 *
048 * @return the error message
049 */
050 public String getMessage();
051
052 /**
053 * Returns the error message of the <code>Throwable</code> in the chain
054 * of <code>Throwable</code>s at the specified index, numbered from 0.
055 *
056 * @param index the index of the <code>Throwable</code> in the chain of
057 * <code>Throwable</code>s
058 * @return the error message, or null if the <code>Throwable</code> at the
059 * specified index in the chain does not contain a message
060 * @throws IndexOutOfBoundsException if the <code>index</code> argument is
061 * negative or not less than the count of <code>Throwable</code>s in the
062 * chain
063 */
064 public String getMessage(int index);
065
066 /**
067 * Returns the error message of this and any nested <code>Throwable</code>s
068 * in an array of Strings, one element for each message. Any
069 * <code>Throwable</code> not containing a message is represented in the
070 * array by a null. This has the effect of cause the length of the returned
071 * array to be equal to the result of the {@link #getThrowableCount()}
072 * operation.
073 *
074 * @return the error messages
075 */
076 public String[] getMessages();
077
078 /**
079 * Returns the <code>Throwable</code> in the chain of
080 * <code>Throwable</code>s at the specified index, numbered from 0.
081 *
082 * @param index the index, numbered from 0, of the <code>Throwable</code> in
083 * the chain of <code>Throwable</code>s
084 * @return the <code>Throwable</code>
085 * @throws IndexOutOfBoundsException if the <code>index</code> argument is
086 * negative or not less than the count of <code>Throwable</code>s in the
087 * chain
088 */
089 public Throwable getThrowable(int index);
090
091 /**
092 * Returns the number of nested <code>Throwable</code>s represented by
093 * this <code>Nestable</code>, including this <code>Nestable</code>.
094 *
095 * @return the throwable count
096 */
097 public int getThrowableCount();
098
099 /**
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 }