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 <a href="mailto:dlr@collab.net">Daniel Rall</a>
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 437554 2006-08-28 06:21:41Z bayard $
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: }
|