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    }