DESY ACOP Beans Home

com.cosylab.util
Class CommonException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.cosylab.util.CommonException

All Implemented Interfaces:

CommonThrowable, java.io.Serializable

Direct Known Subclasses:

CombinedException, CommandException, ConnectionFailed, PlugInException

public class CommonException
extends java.lang.Exception
implements CommonThrowable

This is the basic checked exceptions for the Java projects. In addition to normal Java checked exceptions it provides information about the computer where the exception has occured, as well as instance information about the object, throwing the exception. It also contains hooks for integration with other Java or framework serviecs, in the form of JavaHelp ID string and list of available Swing actions. Several important parameters that are determined at construction time, such as message, instance that is throwing the exception and the possible exception cause (if the exceptions are chained). Other parameters (such as helpID and actions) can be set after construction with their respective property setter methods. Most of the parameters are automatically set in the constructors of CommonException. If the derived exception wishes to override the parameters (such as thread, username, host etc), it may reset them in the derived constructor.

See Also:

Serialized Form

Field Summary

protected javax.swing.Action[]	actions
java.lang.String	caughtIn DOCUMENT ME!
protected java.lang.String	helpID
protected static java.lang.String	host
protected java.lang.Object	instance
protected java.lang.Thread	thread
protected long	timestamp
protected java.lang.String	username
protected java.util.HashMap	values

Constructor Summary

protected	CommonException() Create a new instance of CommonException.
	CommonException(java.lang.Object instance, java.lang.String s) Create an instance of CommonException with a with a specified message string.
	CommonException(java.lang.Object instance, java.lang.String message, java.lang.Throwable t) Create an instance of CommonException by specifying both the string message and a Throwable object that represents the nested exception.

Method Summary

void	caughtIn(java.lang.Object target, 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() Returns the string description of where the exception has been caught or null if it has not been caught.
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.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 hashmap that can hold any key-value pairs that contain internal state of the system or specifically the Object instance raising this exception.
protected void	initialize() Initializes the exception by filling in the host, timestamp, username, thread information.
void	putValue(java.lang.String key, java.lang.Object value) A shortcut to getValues().put(Object key, Object value).
void	setActions(javax.swing.Action[] actions) Sets the actions returned by this exception.
void	setHelpID(java.lang.String helpID) Sets the JavaHelp id under which the help for this specific exception instance may be looked up.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.cosylab.util.CommonThrowable

getMessage

Field Detail

host

protected static java.lang.String host

thread

protected java.lang.Thread thread

instance

protected java.lang.Object instance

values

protected java.util.HashMap values

timestamp

protected long timestamp

helpID

protected java.lang.String helpID

actions

protected javax.swing.Action[] actions

username

protected java.lang.String username

caughtIn

public java.lang.String caughtIn

DOCUMENT ME!

Constructor Detail

CommonException

protected CommonException()

Create a new instance of CommonException. This constructor should normally not be used since it carries no additional exception data.

CommonException

public CommonException(java.lang.Object instance,
                       java.lang.String s)

Create an instance of CommonException with a with a specified message string. The construction is delegated to super.

Parameters:

instance - identifier of the instance throwing this exception

s - message to be printed together with the exception type when the toString() is called.

Throws:

java.lang.NullPointerException - DOCUMENT ME!

CommonException

public CommonException(java.lang.Object instance,
                       java.lang.String message,
                       java.lang.Throwable t)

Create an instance of CommonException by specifying both the string message and a Throwable object that represents the nested exception.

Parameters:

instance - identifier of the instance throwing this exception

message - a string message passed to super

t - an instance of Throwable that caused this to be thrown, can be null

Throws:

java.lang.NullPointerException - DOCUMENT ME!

Method Detail

caughtIn

public void caughtIn(java.lang.Object target,
                     java.lang.String method)

Call this method if the exception is caught. Provides additional debugging info.

Specified by:

caughtIn in interface CommonThrowable

Parameters:

target - Object in which this exception was caught

method - method name without parenthesis of prefixed class name

getCaughtIn

public java.lang.String getCaughtIn()

Returns the string description of where the exception has been caught or null if it has not been caught.

Specified by:

getCaughtIn in interface CommonThrowable

Returns:

String "className::method" of where exception has been caught

getHost

public java.lang.String getHost()

Return the host this exception was generated on, if the JVM has access to such data.

Specified by:

getHost in interface CommonThrowable

Returns:

host name

getParent

public java.lang.Throwable getParent()

Return the parent exception that caused this exception to be thrown.

Specified by:

getParent in interface CommonThrowable

Returns:

parent exception

getThread

public 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.

Specified by:

getThread in interface CommonThrowable

Returns:

thread in which this exception was instantiated

getTimestamp

public long getTimestamp()

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

Specified by:

getTimestamp in interface CommonThrowable

Returns:

exception creation timestamp

getValues

public java.util.Map getValues()

Returns a hashmap that can hold any key-value pairs that contain internal state of the system or specifically the Object instance raising this exception. Such data may help in debugging.

Note! Try to store serialized vaues not to introduce memory leaks.

Specified by:

getValues in interface CommonThrowable

Returns:

additional data

initialize

protected void initialize()

Initializes the exception by filling in the host, timestamp, username, thread information. Subclasses should override this method (but still call it from the overridden version) to provide specialized initialization.

putValue

public void putValue(java.lang.String key,
                     java.lang.Object value)

A shortcut to getValues().put(Object key, Object value). Convenience method. Also converts value to string, not to produce memory leak.

Specified by:

putValue in interface CommonThrowable

Parameters:

key - key under which the value will be stored in the hashtable

value - value for the key, should have toString() overriden to allow for a more informative display

getActions

public javax.swing.Action[] getActions()

Description copied from interface: CommonThrowable

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).

Specified by:

getActions in interface CommonThrowable

Returns:

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

See Also:

CommonThrowable.getActions()

getHelpID

public java.lang.String getHelpID()

Description copied from interface: CommonThrowable

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.

Specified by:

getHelpID in interface CommonThrowable

Returns:

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

See Also:

CommonThrowable.getHelpID()

getInstance

public java.lang.Object getInstance()

Description copied from interface: CommonThrowable

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.

Specified by:

getInstance in interface CommonThrowable

Returns:

Object instance data

See Also:

CommonThrowable.getInstance()

getUsername

public java.lang.String getUsername()

Description copied from interface: CommonThrowable

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).

Specified by:

getUsername in interface CommonThrowable

Returns:

String user name

See Also:

CommonThrowable.getUsername()

getValue

public java.lang.Object getValue(java.lang.String key)

Description copied from interface: CommonThrowable

Returns the value stored under a given key in the map of values.

Specified by:

getValue in interface CommonThrowable

Parameters:

key - the key to look up

Returns:

Object the value returned or null if no value is stored under this key

See Also:

CommonThrowable.getValue(String)

setActions

public void setActions(javax.swing.Action[] actions)

Sets the actions returned by this exception. Such actions will be displayed in the GUI when the exception is caught and handled.

Parameters:

actions - actions to display

setHelpID

public void setHelpID(java.lang.String helpID)

Sets the JavaHelp id under which the help for this specific exception instance may be looked up. This can be set for exceptions that happen more frequently (such as some improper configuration etc) to enable the users to get step-by-step help.

Parameters:

helpID - the JavaHelp identification