    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    }