Nestable


1   /* ====================================================================
2    * The Apache Software License, Version 1.1
3    *
4    * Copyright (c) 2002-2003 The Apache Software Foundation.  All rights
5    * reserved.
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution, if
20   *    any, must include the following acknowledgement:
21   *       "This product includes software developed by the
22   *        Apache Software Foundation (http://www.apache.org/)."
23   *    Alternately, this acknowledgement may appear in the software itself,
24   *    if and wherever such third-party acknowledgements normally appear.
25   *
26   * 4. The names "The Jakarta Project", "Commons", and "Apache Software
27   *    Foundation" must not be used to endorse or promote products derived
28   *    from this software without prior written permission. For written
29   *    permission, please contact apache@apache.org.
30   *
31   * 5. Products derived from this software may not be called "Apache"
32   *    nor may "Apache" appear in their names without prior written
33   *    permission of the Apache Software Foundation.
34   *
35   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46   * SUCH DAMAGE.
47   * ====================================================================
48   *
49   * This software consists of voluntary contributions made by many
50   * individuals on behalf of the Apache Software Foundation.  For more
51   * information on the Apache Software Foundation, please see
52   * <http://www.apache.org/>.
53   */
54  package org.hibernate.exception;
55  
56  import java.io.PrintStream  ;
57  import java.io.PrintWriter  ;
58  
59  /**
60   * An interface to be implemented by {@link java.lang.Throwable}
61   * extensions which would like to be able to nest root exceptions
62   * inside themselves.
63   *
64   * @author <a HREF="mailto:dlr@collab.net">Daniel Rall</a>
65   * @author <a HREF="mailto:knielsen@apache.org">Kasper Nielsen</a>
66   * @author <a HREF="mailto:steven@caswell.name">Steven Caswell</a>
67   * @author Pete Gieser
68   * @version $Id: Nestable.java,v 1.2 2004/11/21 00:11:27 pgmjsd Exp $
69   * @since 1.0
70   */
71  public interface Nestable {
72  
73      /**
74       * Returns the reference to the exception or error that caused the
75       * exception implementing the <code>Nestable</code> to be thrown.
76       *
77       * @return throwable that caused the original exception
78       */
79      public Throwable   getCause();
80  
81      /**
82       * Returns the error message of this and any nested
83       * <code>Throwable</code>.
84       *
85       * @return the error message
86       */
87      public String   getMessage();
88  
89      /**
90       * Returns the error message of the <code>Throwable</code> in the chain
91       * of <code>Throwable</code>s at the specified index, numbererd from 0.
92       *
93       * @param index the index of the <code>Throwable</code> in the chain of
94       *              <code>Throwable</code>s
95       * @return the error message, or null if the <code>Throwable</code> at the
96       *         specified index in the chain does not contain a message
97       * @throws IndexOutOfBoundsException if the <code>index</code> argument is
98       *                                   negative or not less than the count of <code>Throwable</code>s in the
99       *                                   chain
100      */
101     public String   getMessage(int index);
102 
103     /**
104      * Returns the error message of this and any nested <code>Throwable</code>s
105      * in an array of Strings, one element for each message. Any
106      * <code>Throwable</code> not containing a message is represented in the
107      * array by a null. This has the effect of cause the length of the returned
108      * array to be equal to the result of the {@link #getThrowableCount()}
109      * operation.
110      *
111      * @return the error messages
112      */
113     public String  [] getMessages();
114 
115     /**
116      * Returns the <code>Throwable</code> in the chain of
117      * <code>Throwable</code>s at the specified index, numbererd from 0.
118      *
119      * @param index the index, numbered from 0, of the <code>Throwable</code> in
120      *              the chain of <code>Throwable</code>s
121      * @return the <code>Throwable</code>
122      * @throws IndexOutOfBoundsException if the <code>index</code> argument is
123      *                                   negative or not less than the count of <code>Throwable</code>s in the
124      *                                   chain
125      */
126     public Throwable   getThrowable(int index);
127 
128     /**
129      * Returns the number of nested <code>Throwable</code>s represented by
130      * this <code>Nestable</code>, including this <code>Nestable</code>.
131      *
132      * @return the throwable count
133      */
134     public int getThrowableCount();
135 
136     /**
137      * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
138      * in an array of <code>Throwable</code>s, one element for each
139      * <code>Throwable</code>.
140      *
141      * @return the <code>Throwable</code>s
142      */
143     public Throwable  [] getThrowables();
144 
145     /**
146      * Returns the index, numbered from 0, of the first occurrence of the
147      * specified type in the chain of <code>Throwable</code>s, or -1 if the
148      * specified type is not found in the chain.
149      *
150      * @param type <code>Class</code> to be found
151      * @return index of the first occurrence of the type in the chain, or -1 if
152      *         the type is not found
153      */
154     public int indexOfThrowable(Class   type);
155 
156     /**
157      * Returns the index, numbered from 0, of the first <code>Throwable</code>
158      * that matches the specified type in the chain of <code>Throwable</code>s
159      * with an index greater than or equal to the specified index, or -1 if
160      * the type is not found.
161      *
162      * @param type      <code>Class</code> to be found
163      * @param fromIndex the index, numbered from 0, of the starting position in
164      *                  the chain to be searched
165      * @return index of the first occurrence of the type in the chain, or -1 if
166      *         the type is not found
167      * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
168      *                                   is negative or not less than the count of <code>Throwable</code>s in the
169      *                                   chain
170      */
171     public int indexOfThrowable(Class   type, int fromIndex);
172 
173     /**
174      * Prints the stack trace of this exception to the specified print
175      * writer.  Includes information from the exception, if any,
176      * which caused this exception.
177      *
178      * @param out <code>PrintWriter</code> to use for output.
179      */
180     public void printStackTrace(PrintWriter   out);
181 
182     /**
183      * Prints the stack trace of this exception to the specified print
184      * stream.  Includes inforamation from the exception, if any,
185      * which caused this exception.
186      *
187      * @param out <code>PrintStream</code> to use for output.
188      */
189     public void printStackTrace(PrintStream   out);
190 
191     /**
192      * Prints the stack trace for this exception only--root cause not
193      * included--using the provided writer.  Used by {@link
194      * org.apache.commons.lang.exception.NestableDelegate} to write
195      * individual stack traces to a buffer.  The implementation of
196      * this method should call
197      * <code>super.printStackTrace(out);</code> in most cases.
198      *
199      * @param out The writer to use.
200      */
201     public void printPartialStackTrace(PrintWriter   out);
202 
203 }
204
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags