001: /* ====================================================================
002: * The Apache Software License, Version 1.1
003: *
004: * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
005: * reserved.
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * 1. Redistributions of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: *
014: * 2. Redistributions in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * 3. The end-user documentation included with the redistribution, if
020: * any, must include the following acknowledgement:
021: * "This product includes software developed by the
022: * Apache Software Foundation (http://www.apache.org/)."
023: * Alternately, this acknowledgement may appear in the software itself,
024: * if and wherever such third-party acknowledgements normally appear.
025: *
026: * 4. The names "The Jakarta Project", "Commons", and "Apache Software
027: * Foundation" must not be used to endorse or promote products derived
028: * from this software without prior written permission. For written
029: * permission, please contact apache@apache.org.
030: *
031: * 5. Products derived from this software may not be called "Apache"
032: * nor may "Apache" appear in their names without prior written
033: * permission of the Apache Software Foundation.
034: *
035: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
036: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
037: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
038: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
039: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
040: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
041: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
042: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
043: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
044: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
045: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
046: * SUCH DAMAGE.
047: * ====================================================================
048: *
049: * This software consists of voluntary contributions made by many
050: * individuals on behalf of the Apache Software Foundation. For more
051: * information on the Apache Software Foundation, please see
052: * <http://www.apache.org/>.
053: */
054: package org.hibernate.exception;
055:
056: import java.io.PrintStream;
057: import java.io.PrintWriter;
058:
059: /**
060: * An interface to be implemented by {@link java.lang.Throwable}
061: * extensions which would like to be able to nest root exceptions
062: * inside themselves.
063: *
064: * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
065: * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
066: * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
067: * @author Pete Gieser
068: * @version $Id: Nestable.java 4782 2004-11-21 00:11:27Z pgmjsd $
069: * @since 1.0
070: */
071: public interface Nestable {
072:
073: /**
074: * Returns the reference to the exception or error that caused the
075: * exception implementing the <code>Nestable</code> to be thrown.
076: *
077: * @return throwable that caused the original exception
078: */
079: public Throwable getCause();
080:
081: /**
082: * Returns the error message of this and any nested
083: * <code>Throwable</code>.
084: *
085: * @return the error message
086: */
087: public String getMessage();
088:
089: /**
090: * Returns the error message of the <code>Throwable</code> in the chain
091: * of <code>Throwable</code>s at the specified index, numbererd from 0.
092: *
093: * @param index the index of the <code>Throwable</code> in the chain of
094: * <code>Throwable</code>s
095: * @return the error message, or null if the <code>Throwable</code> at the
096: * specified index in the chain does not contain a message
097: * @throws IndexOutOfBoundsException if the <code>index</code> argument is
098: * negative or not less than the count of <code>Throwable</code>s in the
099: * 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, numbererd 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 inforamation 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.apache.commons.lang.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: }
|