Java tutorial
/* * 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 <a href="mailto:dlr@collab.net">Daniel Rall</a> * @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 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 <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 * <code>Throwable</code>. * * @return the error message */ public String getMessage(); /** * 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 <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 <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 <code>Throwable</code>s represented by * this <code>Nestable</code>, including this <code>Nestable</code>. * * @return the throwable count */ public int getThrowableCount(); /** * 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 <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 <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. * * @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. * * @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 * {@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); }