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 }