1 /*
2 * Copyright 2007-2011 smartics, Kronseder & Reiner GmbH
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 de.smartics.exceptions;
17
18 import java.util.Date;
19
20 import de.smartics.exceptions.core.Code;
21 import de.smartics.exceptions.core.ExceptionId;
22
23 /**
24 * Interface defines the core exception features. It is required to have a
25 * common type for the checked and runtime exception types.
26 *
27 * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
28 * @version $Revision:591 $
29 */
30 public interface CoreException
31 {
32 // ********************************* Fields *********************************
33
34 // --- constants ------------------------------------------------------------
35
36 // ****************************** Initializer *******************************
37
38 // ****************************** Inner Classes *****************************
39
40 // ********************************* Methods ********************************
41
42 // --- get&set --------------------------------------------------------------
43
44 /**
45 * Returns the unique identifier of the exception. The identifier is used to
46 * track an exception in different tiers.
47 * <p>
48 * This identifier must never be <code>null</code>.
49 *
50 * @return the unique identifier of the exception.
51 */
52 ExceptionId<?> getId();
53
54 /**
55 * Returns the error or exception code of the exception.
56 * <p>
57 * This code must never be <code>null</code>.
58 *
59 * @return the error or exception code of the exception.
60 */
61 Code getCode();
62
63 /**
64 * Returns the time the exception has been raised. The time instance is
65 * created and stored as soon as the exception is constructed.
66 *
67 * @return the time the exception has been raised.
68 */
69 Date getTime();
70
71 /**
72 * Returns the cause of this throwable or <code>null</code> if the cause is
73 * nonexistent or unknown. (The cause is the throwable that caused this
74 * throwable to get thrown.)
75 * <p>
76 * This implementation returns the cause that was supplied via one of the
77 * constructors requiring a <tt>Throwable</tt>. While it is typically
78 * unnecessary to override this method, a subclass can override it to return a
79 * cause set by some other means. This is appropriate for a
80 * "legacy chained throwable" that predates the addition of chained exceptions
81 * to <tt>Throwable</tt>. Note that it is <i>not</i> necessary to override any
82 * of the <tt>PrintStackTrace</tt> methods, all of which invoke the
83 * <tt>getCause</tt> method to determine the cause of a throwable.
84 *
85 * @return the cause of this throwable or <code>null</code> if the cause is
86 * nonexistent or unknown.
87 */
88 Throwable getCause();
89
90 /**
91 * Provides programmatic access to the stack trace information printed by
92 * {@link Throwable#printStackTrace()}. Returns an array of stack trace
93 * elements, each representing one stack frame. The zeroth element of the
94 * array (assuming the array's length is non-zero) represents the top of the
95 * stack, which is the last method invocation in the sequence. Typically, this
96 * is the point at which this throwable was created and thrown. The last
97 * element of the array (assuming the array's length is non-zero) represents
98 * the bottom of the stack, which is the first method invocation in the
99 * sequence.
100 * <p>
101 * Some virtual machines may, under some circumstances, omit one or more stack
102 * frames from the stack trace. In the extreme case, a virtual machine that
103 * has no stack trace information concerning this throwable is permitted to
104 * return a zero-length array from this method. Generally speaking, the array
105 * returned by this method will contain one element for every frame that would
106 * be printed by <tt>printStackTrace</tt>.
107 *
108 * @return an array of stack trace elements representing the stack trace
109 * pertaining to this throwable.
110 */
111 StackTraceElement[] getStackTrace();
112
113 /**
114 * Sets the stack trace elements that will be returned by
115 * {@link Throwable#getStackTrace()} and printed by
116 * {@link Throwable#printStackTrace()} and related methods. This method, which
117 * is designed for use by RPC frameworks and other advanced systems, allows
118 * the client to override the default stack trace that is either generated by
119 * {@link Throwable#fillInStackTrace()} when a throwable is constructed or
120 * deserialized when a throwable is read from a serialization stream.
121 *
122 * @param stackTrace the stack trace elements to be associated with this
123 * <code>Throwable</code>. The specified array is copied by this
124 * call; changes in the specified array after the method invocation
125 * returns will have no affect on this <code>Throwable</code>'s stack
126 * trace.
127 * @throws NullPointerException if <code>stackTrace</code> is
128 * <code>null</code> , or if any of the elements of
129 * <code>stackTrace</code> are <code>null</code>
130 */
131 void setStackTrace(StackTraceElement[] stackTrace)
132 throws NullPointerException;
133
134 /**
135 * Returns the detail message string of this throwable.
136 *
137 * @return the detail message string of this <tt>Throwable</tt> instance
138 * (which may be <tt>null</tt>).
139 */
140 String getMessage();
141
142 /**
143 * Creates a localized description of this throwable. Subclasses may override
144 * this method in order to produce a locale-specific message. For subclasses
145 * that do not override this method, the default implementation returns the
146 * same result as <code>getMessage()</code>.
147 *
148 * @return The localized description of this throwable.
149 */
150 String getLocalizedMessage();
151
152 // --- business -------------------------------------------------------------
153
154 /**
155 * Truncates the cause from the exception dependent on the
156 * {@link de.smartics.exceptions.core.ThrowableHandleMode} set to the
157 * thread-local context. After running this method the cause will be truncate
158 * and the full stack trace will no longer be available.
159 */
160 void truncateCause();
161
162 // --- object basics --------------------------------------------------------
163 }