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    }