/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.lang.exception;

import java.io.PrintStream;
import java.io.PrintWriter;

An interface to be implemented by Throwable extensions which would like to be able to nest root exceptions inside themselves. 
Author:
Daniel L. Rall, Kasper Nielsen, Steven Caswell, Pete Gieser
Since:
1.0
Version:
$Id: Nestable.java 512889 2007-02-28 18:18:20Z dlr $/**
 * An interface to be implemented by {@link java.lang.Throwable}
 * extensions which would like to be able to nest root exceptions
 * inside themselves.
 *
 * @author Daniel L. Rall
 * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
 * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
 * @author Pete Gieser
 * @since 1.0
 * @version $Id: Nestable.java 512889 2007-02-28 18:18:20Z dlr $
 */
public interface Nestable {
    
    
Returns the reference to the exception or error that caused the
exception implementing the Nestable to be thrown.
Returns:
throwable that caused the original exception/**
     * Returns the reference to the exception or error that caused the
     * exception implementing the <code>Nestable</code> to be thrown.
     *
     * @return throwable that caused the original exception
     */
    public Throwable getCause();

    
Returns the error message of this and any nested
Throwable.
Returns:
the error message/**
     * Returns the error message of this and any nested
     * <code>Throwable</code>.
     *
     * @return the error message
     */
    public String getMessage();

    
Returns the error message of the Throwable in the chain
of Throwables at the specified index, numbered from 0.
Params:
index – the index of the Throwable in the chain of
Throwables
Throws:
IndexOutOfBoundsException – if the index argument is
negative or not less than the count of Throwables in the
chain
Returns:
the error message, or null if the Throwable at the
specified index in the chain does not contain a message/**
     * Returns the error message of the <code>Throwable</code> in the chain
     * of <code>Throwable</code>s at the specified index, numbered from 0.
     *
     * @param index the index of the <code>Throwable</code> in the chain of
     * <code>Throwable</code>s
     * @return the error message, or null if the <code>Throwable</code> at the
     * specified index in the chain does not contain a message
     * @throws IndexOutOfBoundsException if the <code>index</code> argument is
     * negative or not less than the count of <code>Throwable</code>s in the
     * chain
     */
    public String getMessage(int index);

    
Returns the error message of this and any nested Throwables
in an array of Strings, one element for each message. Any
Throwable not containing a message is represented in the array by a null. This has the effect of cause the length of the returned array to be equal to the result of the getThrowableCount() operation. 
Returns:
the error messages/**
     * Returns the error message of this and any nested <code>Throwable</code>s
     * in an array of Strings, one element for each message. Any
     * <code>Throwable</code> not containing a message is represented in the
     * array by a null. This has the effect of cause the length of the returned
     * array to be equal to the result of the {@link #getThrowableCount()}
     * operation.
     *
     * @return the error messages
     */
    public String[] getMessages();

    
Returns the Throwable in the chain of
Throwables at the specified index, numbered from 0.
Params:
index – the index, numbered from 0, of the Throwable in
the chain of Throwables
Throws:
IndexOutOfBoundsException – if the index argument is
negative or not less than the count of Throwables in the
chain
Returns:
the Throwable/**
     * Returns the <code>Throwable</code> in the chain of
     * <code>Throwable</code>s at the specified index, numbered from 0.
     *
     * @param index the index, numbered from 0, of the <code>Throwable</code> in
     * the chain of <code>Throwable</code>s
     * @return the <code>Throwable</code>
     * @throws IndexOutOfBoundsException if the <code>index</code> argument is
     * negative or not less than the count of <code>Throwable</code>s in the
     * chain
     */
    public Throwable getThrowable(int index);

    
Returns the number of nested Throwables represented by
this Nestable, including this Nestable.
Returns:
the throwable count/**
     * Returns the number of nested <code>Throwable</code>s represented by
     * this <code>Nestable</code>, including this <code>Nestable</code>.
     *
     * @return the throwable count
     */
    public int getThrowableCount();

    
Returns this Nestable and any nested Throwables
in an array of Throwables, one element for each
Throwable.
Returns:
the Throwables/**
     * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
     * in an array of <code>Throwable</code>s, one element for each
     * <code>Throwable</code>.
     *
     * @return the <code>Throwable</code>s
     */
    public Throwable[] getThrowables();

    
Returns the index, numbered from 0, of the first occurrence of the
specified type, or a subclass, in the chain of Throwables.
The method returns -1 if the specified type is not found in the chain.

NOTE: From v2.1, we have clarified the Nestable interface such that this method matches subclasses. If you want to NOT match subclasses, please use ExceptionUtils.indexOfThrowable(Throwable, Class) (which is avaiable in all versions of lang). 
Params:
type –  the type to find, subclasses match, null returns -1
Returns:
index of the first occurrence of the type in the chain, or -1 if
the type is not found/**
     * Returns the index, numbered from 0, of the first occurrence of the
     * specified type, or a subclass, in the chain of <code>Throwable</code>s.
     * The method returns -1 if the specified type is not found in the chain.
     * <p>
     * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
     * such that this method matches subclasses.
     * If you want to NOT match subclasses, please use
     * {@link ExceptionUtils#indexOfThrowable(Throwable, Class)}
     * (which is avaiable in all versions of lang).
     *
     * @param type  the type to find, subclasses match, null returns -1
     * @return index of the first occurrence of the type in the chain, or -1 if
     * the type is not found
     */
    public int indexOfThrowable(Class type);

    
Returns the index, numbered from 0, of the first Throwable
that matches the specified type, or a subclass, in the chain of Throwables
with an index greater than or equal to the specified index.
The method returns -1 if the specified type is not found in the chain.

NOTE: From v2.1, we have clarified the Nestable interface such that this method matches subclasses. If you want to NOT match subclasses, please use ExceptionUtils.indexOfThrowable(Throwable, Class, int) (which is avaiable in all versions of lang). 
Params:
type –  the type to find, subclasses match, null returns -1
fromIndex – the index, numbered from 0, of the starting position in
the chain to be searched
Throws:
IndexOutOfBoundsException – if the fromIndex argument
is negative or not less than the count of Throwables in the
chain
Returns:
index of the first occurrence of the type in the chain, or -1 if
the type is not found/**
     * Returns the index, numbered from 0, of the first <code>Throwable</code>
     * that matches the specified type, or a subclass, in the chain of <code>Throwable</code>s
     * with an index greater than or equal to the specified index.
     * The method returns -1 if the specified type is not found in the chain.
     * <p>
     * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
     * such that this method matches subclasses.
     * If you want to NOT match subclasses, please use
     * {@link ExceptionUtils#indexOfThrowable(Throwable, Class, int)}
     * (which is avaiable in all versions of lang).
     *
     * @param type  the type to find, subclasses match, null returns -1
     * @param fromIndex the index, numbered from 0, of the starting position in
     * the chain to be searched
     * @return index of the first occurrence of the type in the chain, or -1 if
     * the type is not found
     * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
     * is negative or not less than the count of <code>Throwable</code>s in the
     * chain
     */
    public int indexOfThrowable(Class type, int fromIndex);

    
Prints the stack trace of this exception to the specified print
writer.  Includes information from the exception, if any,
which caused this exception.
Params:
out – PrintWriter to use for output./**
     * Prints the stack trace of this exception to the specified print
     * writer.  Includes information from the exception, if any,
     * which caused this exception.
     *
     * @param out <code>PrintWriter</code> to use for output.
     */
    public void printStackTrace(PrintWriter out);

    
Prints the stack trace of this exception to the specified print
stream.  Includes information from the exception, if any,
which caused this exception.
Params:
out – PrintStream to use for output./**
     * Prints the stack trace of this exception to the specified print
     * stream.  Includes information from the exception, if any,
     * which caused this exception.
     *
     * @param out <code>PrintStream</code> to use for output.
     */
    public void printStackTrace(PrintStream out);

    
Prints the stack trace for this exception only--root cause not included--using the provided writer. Used by NestableDelegate to write individual stack traces to a buffer. The implementation of this method should call super.printStackTrace(out); in most cases.
Params:
out – The writer to use./**
     * Prints the stack trace for this exception only--root cause not
     * included--using the provided writer.  Used by
     * {@link org.apache.commons.lang.exception.NestableDelegate} to write
     * individual stack traces to a buffer.  The implementation of
     * this method should call
     * <code>super.printStackTrace(out);</code> in most cases.
     *
     * @param out The writer to use.
     */
    public void printPartialStackTrace(PrintWriter out);
    
}