001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 *
019 */
020 package org.apache.directory.shared.ldap.util;
021
022
023 import java.io.PrintStream;
024 import java.io.PrintWriter;
025
026
027 /**
028 * An interface to be implemented by {@link java.lang.Throwable} extensions
029 * which would like to be able to nest root exceptions inside themselves.
030 *
031 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
032 */
033 public interface Nestable
034 {
035
036 /**
037 * Returns the reference to the exception or error that caused the exception
038 * 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 /**
046 * Returns the error message of this and any nested <code>Throwable</code>.
047 *
048 * @return the error message
049 */
050 public String getMessage();
051
052
053 /**
054 * Returns the error message of the <code>Throwable</code> in the chain of
055 * <code>Throwable</code>s at the specified index, numbered from 0.
056 *
057 * @param index
058 * the index of the <code>Throwable</code> in the chain of
059 * <code>Throwable</code>s
060 * @return the error message, or null if the <code>Throwable</code> at the
061 * specified index in the chain does not contain a message
062 * @throws IndexOutOfBoundsException
063 * if the <code>index</code> argument is negative or not less
064 * than the count of <code>Throwable</code>s in the chain
065 */
066 public String getMessage( int index );
067
068
069 /**
070 * Returns the error message of this and any nested <code>Throwable</code>s
071 * in an array of Strings, one element for each message. Any
072 * <code>Throwable</code> not containing a message is represented in the
073 * array by a null. This has the effect of cause the length of the returned
074 * array to be equal to the result of the {@link #getThrowableCount()}
075 * operation.
076 *
077 * @return the error messages
078 */
079 public String[] getMessages();
080
081
082 /**
083 * Returns the <code>Throwable</code> in the chain of
084 * <code>Throwable</code>s at the specified index, numbered from 0.
085 *
086 * @param index
087 * the index, numbered from 0, of the <code>Throwable</code> in
088 * the chain of <code>Throwable</code>s
089 * @return the <code>Throwable</code>
090 * @throws IndexOutOfBoundsException
091 * if the <code>index</code> argument is negative or not less
092 * than the count of <code>Throwable</code>s in the chain
093 */
094 public Throwable getThrowable( int index );
095
096
097 /**
098 * Returns the number of nested <code>Throwable</code>s represented by
099 * this <code>Nestable</code>, including this <code>Nestable</code>.
100 *
101 * @return the throwable count
102 */
103 public int getThrowableCount();
104
105
106 /**
107 * Returns this <code>Nestable</code> and any nested
108 * <code>Throwable</code>s in an array of <code>Throwable</code>s, one
109 * element for each <code>Throwable</code>.
110 *
111 * @return the <code>Throwable</code>s
112 */
113 public Throwable[] getThrowables();
114
115
116 /**
117 * Returns the index, numbered from 0, of the first occurrence of the
118 * specified type in the chain of <code>Throwable</code>s, or -1 if the
119 * specified type is not found in the chain.
120 *
121 * @param type
122 * <code>Class</code> to be found
123 * @return index of the first occurrence of the type in the chain, or -1 if
124 * the type is not found
125 */
126 public int indexOfThrowable( Class type );
127
128
129 /**
130 * Returns the index, numbered from 0, of the first <code>Throwable</code>
131 * that matches the specified type in the chain of <code>Throwable</code>s
132 * with an index greater than or equal to the specified index, or -1 if the
133 * type is not found.
134 *
135 * @param type
136 * <code>Class</code> to be found
137 * @param fromIndex
138 * the index, numbered from 0, of the starting position in the
139 * 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
143 * if the <code>fromIndex</code> argument is negative or not
144 * less than the count of <code>Throwable</code>s in the
145 * chain
146 */
147 public int indexOfThrowable( Class type, int fromIndex );
148
149
150 /**
151 * Prints the stack trace of this exception to the specified print writer.
152 * Includes information from the exception, if any, which caused this
153 * exception.
154 *
155 * @param out
156 * <code>PrintWriter</code> to use for output.
157 */
158 public void printStackTrace( PrintWriter out );
159
160
161 /**
162 * Prints the stack trace of this exception to the specified print stream.
163 * Includes information from the exception, if any, which caused this
164 * exception.
165 *
166 * @param out
167 * <code>PrintStream</code> to use for output.
168 */
169 public void printStackTrace( PrintStream out );
170
171
172 /**
173 * Prints the stack trace for this exception only--root cause not
174 * included--using the provided writer. Used by
175 * {@link "org.apache.commons.lang.exception.NestableDelegate"} to write individual
176 * stack traces to a buffer. The implementation of this method should call
177 * <code>super.printStackTrace(out);</code> in most cases.
178 *
179 * @param out
180 * The writer to use.
181 */
182 public void printPartialStackTrace( PrintWriter out );
183
184 }