Nestable


1   /*
2    * Copyright 2002-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.lang.exception;
17  
18  import java.io.PrintStream  ;
19  import java.io.PrintWriter  ;
20  
21  /**
22   * An interface to be implemented by {@link java.lang.Throwable}
23   * extensions which would like to be able to nest root exceptions
24   * inside themselves.
25   *
26   * @author <a HREF="mailto:dlr@collab.net">Daniel Rall</a>
27   * @author <a HREF="mailto:knielsen@apache.org">Kasper Nielsen</a>
28   * @author <a HREF="mailto:steven@caswell.name">Steven Caswell</a>
29   * @author Pete Gieser
30   * @since 1.0
31   * @version $Id: Nestable.java 161243 2005-04-14 04:30:28Z ggregory $
32   */
33  public interface Nestable {
34      
35      /**
36       * Returns the reference to the exception or error that caused the
37       * exception implementing the <code>Nestable</code> to be thrown.
38       *
39       * @return throwable that caused the original exception
40       */
41      public Throwable   getCause();
42  
43      /**
44       * Returns the error message of this and any nested
45       * <code>Throwable</code>.
46       *
47       * @return the error message
48       */
49      public String   getMessage();
50  
51      /**
52       * Returns the error message of the <code>Throwable</code> in the chain
53       * of <code>Throwable</code>s at the specified index, numbered from 0.
54       *
55       * @param index the index of the <code>Throwable</code> in the chain of
56       * <code>Throwable</code>s
57       * @return the error message, or null if the <code>Throwable</code> at the
58       * specified index in the chain does not contain a message
59       * @throws IndexOutOfBoundsException if the <code>index</code> argument is
60       * negative or not less than the count of <code>Throwable</code>s in the
61       * chain
62       */
63      public String   getMessage(int index);
64  
65      /**
66       * Returns the error message of this and any nested <code>Throwable</code>s
67       * in an array of Strings, one element for each message. Any
68       * <code>Throwable</code> not containing a message is represented in the
69       * array by a null. This has the effect of cause the length of the returned
70       * array to be equal to the result of the {@link #getThrowableCount()}
71       * operation.
72       *
73       * @return the error messages
74       */
75      public String  [] getMessages();
76  
77      /**
78       * Returns the <code>Throwable</code> in the chain of
79       * <code>Throwable</code>s at the specified index, numbered from 0.
80       *
81       * @param index the index, numbered from 0, of the <code>Throwable</code> in
82       * the chain of <code>Throwable</code>s
83       * @return the <code>Throwable</code>
84       * @throws IndexOutOfBoundsException if the <code>index</code> argument is
85       * negative or not less than the count of <code>Throwable</code>s in the
86       * chain
87       */
88      public Throwable   getThrowable(int index);
89  
90      /**
91       * Returns the number of nested <code>Throwable</code>s represented by
92       * this <code>Nestable</code>, including this <code>Nestable</code>.
93       *
94       * @return the throwable count
95       */
96      public int getThrowableCount();
97  
98      /**
99       * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
100      * in an array of <code>Throwable</code>s, one element for each
101      * <code>Throwable</code>.
102      *
103      * @return the <code>Throwable</code>s
104      */
105     public Throwable  [] getThrowables();
106 
107     /**
108      * Returns the index, numbered from 0, of the first occurrence of the
109      * specified type, or a subclass, in the chain of <code>Throwable</code>s.
110      * The method returns -1 if the specified type is not found in the chain.
111      * <p>
112      * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
113      * such that this method matches subclasses.
114      * If you want to NOT match subclasses, please use
115      * {@link ExceptionUtils#indexOfThrowable(Throwable, Class)}
116      * (which is avaiable in all versions of lang).
117      *
118      * @param type  the type to find, subclasses match, null returns -1
119      * @return index of the first occurrence of the type in the chain, or -1 if
120      * the type is not found
121      */
122     public int indexOfThrowable(Class   type);
123 
124     /**
125      * Returns the index, numbered from 0, of the first <code>Throwable</code>
126      * that matches the specified type, or a subclass, in the chain of <code>Throwable</code>s
127      * with an index greater than or equal to the specified index.
128      * The method returns -1 if the specified type is not found in the chain.
129      * <p>
130      * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
131      * such that this method matches subclasses.
132      * If you want to NOT match subclasses, please use
133      * {@link ExceptionUtils#indexOfThrowable(Throwable, Class, int)}
134      * (which is avaiable in all versions of lang).
135      *
136      * @param type  the type to find, subclasses match, null returns -1
137      * @param fromIndex the index, numbered from 0, of the starting position in
138      * the chain to be searched
139      * @return index of the first occurrence of the type in the chain, or -1 if
140      * the type is not found
141      * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
142      * is negative or not less than the count of <code>Throwable</code>s in the
143      * chain
144      */
145     public int indexOfThrowable(Class   type, int fromIndex);
146 
147     /**
148      * Prints the stack trace of this exception to the specified print
149      * writer.  Includes information from the exception, if any,
150      * which caused this exception.
151      *
152      * @param out <code>PrintWriter</code> to use for output.
153      */
154     public void printStackTrace(PrintWriter   out);
155 
156     /**
157      * Prints the stack trace of this exception to the specified print
158      * stream.  Includes information from the exception, if any,
159      * which caused this exception.
160      *
161      * @param out <code>PrintStream</code> to use for output.
162      */
163     public void printStackTrace(PrintStream   out);
164 
165     /**
166      * Prints the stack trace for this exception only--root cause not
167      * included--using the provided writer.  Used by
168      * {@link org.apache.commons.lang.exception.NestableDelegate} to write
169      * individual stack traces to a buffer.  The implementation of
170      * this method should call
171      * <code>super.printStackTrace(out);</code> in most cases.
172      *
173      * @param out The writer to use.
174      */
175     public void printPartialStackTrace(PrintWriter   out);
176     
177 }
178
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags