DESY ACOP Beans Home

com.cosylab.util
Interface CommonThrowable

All Known Implementing Classes:
CombinedException, CommandException, CommonException, ConnectionFailed, PlugInException

public interface CommonThrowable

An interface common to exceptions in projects that depend on Java-Common. This is an interface because it can be implemented by both checked exceptions (extending java.lang.Exception) and unchecked exceptions (extending java.lang.RuntimeException), although the later use will probably be not so common. Methods of this interface provide additional information, besides that already contained in Java exceptions (such as message, stack trace elements), that can be used to describe the exception, turn it into a log, or submit it to the support center. By defining a help ID the exceptions can be tied to JavaHelp system as well.

See Also:
Throwable

Method Summary
 void caughtIn(java.lang.Object instance, java.lang.String method)
          Call this method if the exception is caught.
 javax.swing.Action[] getActions()
          Returns a list of suggested actions that can be added to the GUI.
 java.lang.String getCaughtIn()
          When additional info about the exception is provided via caughtIn(Object, String) method, this method should be called to obtain the name of the method that caught the exception together with the name of its declaring class.
 java.lang.String getHelpID()
          Returns the help identifier for this exception.
 java.lang.String getHost()
          Return the host this exception was generated on, if the JVM has access to such data.
 java.lang.Object getInstance()
          Return the data about the instance which raised the exception.
 java.lang.String getMessage()
          Returns the message carried by exception implementing this interface.
 java.lang.Throwable getParent()
          Return the parent exception that caused this exception to be thrown.
 java.lang.Thread getThread()
          Returns the thread of execution in which the constructor of this exception was invoked.
 long getTimestamp()
          Returns the timestamp of the instantiation of this exception.
 java.lang.String getUsername()
          Returns the currently logged in user.
 java.lang.Object getValue(java.lang.String key)
          Returns the value stored under a given key in the map of values.
 java.util.Map getValues()
          Returns a map that can hold any key-value pairs that contain internal state of the system or specifically the Identifiable instance raising this exception.
 void putValue(java.lang.String key, java.lang.Object value)
          Sets a value with a given key in the map of values.
 

Method Detail

caughtIn

void caughtIn(java.lang.Object instance,
              java.lang.String method)
Call this method if the exception is caught. Provides additional debugging info.

Parameters:
method - method name without parenthesis of prefixed class name

getHelpID

java.lang.String getHelpID()
Returns the help identifier for this exception. The help identifier can be provided by the instantiator of the exception to indicate the specific problem for which the exception is being thrown. The help for this problem can then be looked up into the database by help applications. This is indended for problems that are common enough to have dedicated help pages.

Returns:
String help ID used by JavaHelp to look up help for this exception

getUsername

java.lang.String getUsername()
Returns the currently logged in user. This is the user returned by the JVM unless the instance throwing the exception has more specific user information (such as local login).

Returns:
String user name

getHost

java.lang.String getHost()
Return the host this exception was generated on, if the JVM has access to such data.

Returns:
host name

getInstance

java.lang.Object getInstance()
Return the data about the instance which raised the exception. Normally, the exception carries only class data, not instance data. In case of libraries where many models of the same class are instantiated, having a stack trace does not help with problems that are tied to the instance and not to the class (for example remote communication with an instance whose device server crashed). If the object raising an exception does not implement Identifiable interface, it should return the Identifiable of its logically most "proximate" Identifiable instance. Note that while instances of CoreException must provide at least the proximate Identifiable, instances of AssertionFailed may return null in this method.

Returns:
Object instance data

getCaughtIn

java.lang.String getCaughtIn()
When additional info about the exception is provided via caughtIn(Object, String) method, this method should be called to obtain the name of the method that caught the exception together with the name of its declaring class. May return null, if this information is not available.

Returns:
String Name of the method that caught the exception.

getMessage

java.lang.String getMessage()
Returns the message carried by exception implementing this interface.

Returns:
String message of the exception

getParent

java.lang.Throwable getParent()
Return the parent exception that caused this exception to be thrown.

Returns:
parent exception

getThread

java.lang.Thread getThread()
Returns the thread of execution in which the constructor of this exception was invoked. It is presupposed that exception is thrown in the same thread in which it was instantiated.

Returns:
thread in which this exception was instantiated

getTimestamp

long getTimestamp()
Returns the timestamp of the instantiation of this exception. Value is in the format returned by Java System.currentTimeMillis().

Returns:
exception creation timestamp

getValues

java.util.Map getValues()
Returns a map that can hold any key-value pairs that contain internal state of the system or specifically the Identifiable instance raising this exception. Such data may help in debugging.

Returns:
additional data

putValue

void putValue(java.lang.String key,
              java.lang.Object value)
Sets a value with a given key in the map of values.

Parameters:
key - the key under which the value will be stored in the map
value - the value to store

getValue

java.lang.Object getValue(java.lang.String key)
Returns the value stored under a given key in the map of values.

Parameters:
key - the key to look up
Returns:
Object the value returned or null if no value is stored under this key

getActions

javax.swing.Action[] getActions()
Returns a list of suggested actions that can be added to the GUI. For example, an exception could be sent to the system log, or a report could be sent to some Web address, or it could be saved to a file etc. Such procedures should be coded as actions returned by this instance. Note that the instantiation of the actions can be delayed until this method is invoked (lazy creation).

Returns:
Action[] array of actions that can be performed on this exception


Copyright © 2010. All Rights Reserved.