1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of Java-Common.
5 *
6 * Java-Common is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * Java-Common is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with Java-Common. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.util;
21
22 import java.util.Map;
23
24 import javax.swing.Action;
25
26
27 /**
28 * An interface common to exceptions in projects that depend on Java-Common.
29 * This is an interface because it can be implemented by both checked
30 * exceptions (extending <code>java.lang.Exception</code>) and unchecked
31 * exceptions (extending <code>java.lang.RuntimeException</code>), although
32 * the later use will probably be not so common. Methods of this interface
33 * provide additional information, besides that already contained in Java
34 * exceptions (such as message, stack trace elements), that can be used to
35 * describe the exception, turn it into a log, or submit it to the support
36 * center. By defining a help ID the exceptions can be tied to JavaHelp system
37 * as well.
38 *
39 * @see java.lang.Throwable
40 */
41 public interface CommonThrowable
42 {
43 /**
44 * Call this method if the exception is caught. Provides additional
45 * debugging info.
46 *
47 * @param method method name without parenthesis of prefixed class name
48 */
49 void caughtIn(Object instance, String method);
50
51 /**
52 * Returns the help identifier for this exception. The help identifier can
53 * be provided by the instantiator of the exception to indicate the
54 * specific problem for which the exception is being thrown. The help for
55 * this problem can then be looked up into the database by help
56 * applications. This is indended for problems that are common enough to
57 * have dedicated help pages.
58 *
59 * @return String help ID used by JavaHelp to look up help for this
60 * exception
61 */
62 String getHelpID();
63
64 /**
65 * Returns the currently logged in user. This is the user returned by the
66 * JVM <b>unless</b> the instance throwing the exception has more specific
67 * user information (such as local login).
68 *
69 * @return String user name
70 */
71 String getUsername();
72
73 /**
74 * Return the host this exception was generated on, if the JVM has access
75 * to such data.
76 *
77 * @return host name
78 */
79 String getHost();
80
81 /**
82 * Return the data about the instance which raised the exception. Normally,
83 * the exception carries only class data, not instance data. In case of
84 * libraries where many models of the same class are instantiated, having
85 * a stack trace does not help with problems that are tied to the instance
86 * and not to the class (for example remote communication with an instance
87 * whose device server crashed). If the object raising an exception does
88 * not implement <code>Identifiable</code> interface, it should return the
89 * <code>Identifiable</code> of its logically most "proximate"
90 * <code>Identifiable</code> instance. Note that while instances of
91 * <code>CoreException</code> must provide at least the proximate
92 * <code>Identifiable</code>, instances of <code>AssertionFailed</code>
93 * may return <code>null</code> in this method.
94 *
95 * @return Object instance data
96 */
97 Object getInstance();
98
99 /**
100 * When additional info about the exception is provided via
101 * <code>caughtIn(Object, String)</code> method, this method should be
102 * called to obtain the name of the method that caught the exception
103 * together with the name of its declaring class. May return
104 * <code>null</code>, if this information is not available.
105 *
106 * @return String Name of the method that caught the exception.
107 */
108 String getCaughtIn();
109
110 /**
111 * Returns the message carried by exception implementing this interface.
112 *
113 * @return String message of the exception
114 */
115 String getMessage();
116
117 /**
118 * Return the parent exception that caused this exception to be thrown.
119 *
120 * @return parent exception
121 */
122 Throwable getParent();
123
124 /**
125 * Returns the thread of execution in which the constructor of this
126 * exception was invoked. It is presupposed that exception is thrown in
127 * the same thread in which it was instantiated.
128 *
129 * @return thread in which this exception was instantiated
130 */
131 Thread getThread();
132
133 /**
134 * Returns the timestamp of the instantiation of this exception. Value is
135 * in the format returned by Java <code>System.currentTimeMillis()</code>.
136 *
137 * @return exception creation timestamp
138 */
139 long getTimestamp();
140
141 /**
142 * Returns a map that can hold any key-value pairs that contain internal
143 * state of the system or specifically the <code>Identifiable</code>
144 * instance raising this exception. Such data may help in debugging.
145 *
146 * @return additional data
147 */
148 Map getValues();
149
150 /**
151 * Sets a value with a given key in the map of values.
152 *
153 * @param key the key under which the value will be stored in the map
154 * @param value the value to store
155 */
156 void putValue(String key, Object value);
157
158 /**
159 * Returns the value stored under a given key in the map of values.
160 *
161 * @param key the key to look up
162 *
163 * @return Object the value returned or <code>null</code> if no value is
164 * stored under this key
165 */
166 Object getValue(String key);
167
168 /**
169 * Returns a list of suggested actions that can be added to the GUI. For
170 * example, an exception could be sent to the system log, or a report
171 * could be sent to some Web address, or it could be saved to a file etc.
172 * Such procedures should be coded as actions returned by this instance.
173 * Note that the instantiation of the actions can be delayed until this
174 * method is invoked (lazy creation).
175 *
176 * @return Action[] array of actions that can be performed on this
177 * exception
178 */
179 Action[] getActions();
180 }
181
182 /* __oOo__ */