org.apache.commons.lang.exception.Nestable Maven / Gradle / Ivy
Show all versions of commons-lang Show documentation
/*
* 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 {@link java.lang.Throwable}
* extensions which would like to be able to nest root exceptions
* inside themselves.
*
* @author Daniel Rall
* @author Kasper Nielsen
* @author Steven Caswell
* @author Pete Gieser
* @since 1.0
* @version $Id: Nestable.java 437554 2006-08-28 06:21:41Z bayard $
*/
public interface Nestable {
/**
* Returns the reference to the exception or error that caused the
* exception implementing the Nestable to be thrown.
*
* @return throwable that caused the original exception
*/
public Throwable getCause();
/**
* Returns the error message of this and any nested
* Throwable.
*
* @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.
*
* @param index the index of the Throwable in the chain of
* Throwables
* @return the error message, or null if the Throwable at the
* specified index in the chain does not contain a message
* @throws IndexOutOfBoundsException if the index argument is
* negative or not less than the count of Throwables 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 {@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.
*
* @param index the index, numbered from 0, of the Throwable in
* the chain of Throwables
* @return the Throwable
* @throws IndexOutOfBoundsException if the index argument is
* negative or not less than the count of Throwables in the
* chain
*/
public Throwable getThrowable(int index);
/**
* Returns the number of nested Throwables represented by
* this Nestable, including this Nestable.
*
* @return the throwable count
*/
public int getThrowableCount();
/**
* Returns this Nestable and any nested Throwables
* in an array of Throwables, one element for each
* Throwable.
*
* @return the Throwables
*/
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
* {@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
* {@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 fromIndex argument
* is negative or not less than the count of Throwables 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.
*
* @param out PrintWriter 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.
*
* @param out PrintStream 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
* {@link org.apache.commons.lang.exception.NestableDelegate} to write
* individual stack traces to a buffer. The implementation of
* this method should call
* super.printStackTrace(out); in most cases.
*
* @param out The writer to use.
*/
public void printPartialStackTrace(PrintWriter out);
}