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