com.rubecula.util
Class LocalizedException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.rubecula.util.LocalizedException

All Implemented Interfaces:

java.io.Serializable

public abstract class LocalizedException

extends java.lang.Exception

Abstract exception class used for localizable exceptions.

Note that in order to retrieve the (non-localizable) detail message, call getMessage()

Version:

$Revision: 1.3 $

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

protected static java.lang.String	$CausedBy Value: "caused by"
protected static java.lang.String	$Colon Value: ":"
protected static java.lang.String	$FurtherDetail Value: "with further detail"
protected static java.lang.String	$Indent Value: " "
protected static java.lang.String	$Newline Value: "\n"
protected static java.lang.String	$NoLocalizableExplanation Value: " (unspecified detail)"
protected static java.lang.String	$StackCallPrefix Value: "\tat "
protected static java.lang.String	$ThrownBy Value: " thrown by "
protected static java.lang.String	$UnknownMethod Value: "unknown class/method"
protected java.lang.String	nonLocalJunk The non-localizable junk from the key provided (characters from ":" to end inclusive, if any)
private java.lang.String	strClassMethod A field which simply retains the value of the class and method names concatenated together by ".".
protected java.lang.String	strKey The resource-specifying key for this exception

Fields inherited from class java.lang.Exception

Fields inherited from class java.lang.Throwable

Constructor Summary

protected	LocalizedException() You must specify either the text message.
	LocalizedException(java.lang.String key) Construct an exception with the key to the problem.
	LocalizedException(java.lang.String key, java.lang.String detailNonLocalized) Construct an exception with the key to the problem and a non-localizable detail message.
	LocalizedException(java.lang.String key, java.lang.Throwable cause) Construct an exception with the key to the problem and a causal exception.

Method Summary

static java.lang.String	getCaller(java.lang.Throwable e) Get the caller details of the thrower of an exception.
static java.lang.String	getCaller(java.lang.Throwable e, int index) Gets the string representing the indexth caller (stack frame) within the stack trace of an exception.
static java.lang.String	getCallerClassMethod(java.lang.Throwable e) Get the class-method part of the caller string.
java.lang.String	getLocalizedMessage() This method is used by the toString method and indirectly by the printStackTrace methods in order to get a representation of the exception.
abstract java.util.ResourceBundle	getResourceBundle() Method to get a reference to the resource bundle for this class.
static java.lang.String	getStackDumpAsString(java.lang.Throwable e) Utility method to return the current exception stack dump as a String.
void	printStackTrace(java.io.PrintStream s) Prints this LocalizedException and its backtrace to the specified print stream.
java.lang.String	toString() Returns a short description of this throwable object.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

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

Field Detail

strKey

protected java.lang.String strKey

The resource-specifying key for this exception

nonLocalJunk

protected java.lang.String nonLocalJunk

The non-localizable junk from the key provided (characters from ":" to end inclusive, if any)

strClassMethod

private java.lang.String strClassMethod

A field which simply retains the value of the class and method names concatenated together by ".".
This is private because it really doesn't make any sense for anyone to mess with this.

$NoLocalizableExplanation

protected static final java.lang.String $NoLocalizableExplanation

Value: " (unspecified detail)"

See Also:

Constant Field Values

$FurtherDetail

protected static final java.lang.String $FurtherDetail

Value: "with further detail"

See Also:

Constant Field Values

$ThrownBy

protected static final java.lang.String $ThrownBy

Value: " thrown by "

See Also:

Constant Field Values

$UnknownMethod

protected static final java.lang.String $UnknownMethod

Value: "unknown class/method"

See Also:

Constant Field Values

$CausedBy

protected static final java.lang.String $CausedBy

Value: "caused by"

See Also:

Constant Field Values

$Indent

protected static final java.lang.String $Indent

Value: " "

See Also:

Constant Field Values

$Newline

protected static final java.lang.String $Newline

Value: "\n"

See Also:

Constant Field Values

$Colon

protected static final java.lang.String $Colon

Value: ":"

See Also:

Constant Field Values

$StackCallPrefix

protected static final java.lang.String $StackCallPrefix

Value: "\tat "

See Also:

Constant Field Values

Constructor Detail

LocalizedException

public LocalizedException(java.lang.String key,
                          java.lang.String detailNonLocalized)

Construct an exception with the key to the problem and a non-localizable detail message. The latter message is consulted by printStackTrace(java.io.PrintStream) but not by Throwable.toString() nor any of the other printStackTrace methods.

Parameters:

key - A key to a localizable detail message. May be null but it really ought not to be. If it is null, all the string forms of the exception will simply identify themselves by class name which is OK if you are using a very explicit exception class, but if you're using a generic class you will never know WHICH exception was thrown, where. Also, if you are using an explicit exception class with a null key, consider extending BaseException instead of LocalizedException.
The key should be descriptive, especially if you have not provided even a base explanation of the problem in the .properties file.
The key should be unique amongst the potential instances of this exception class within the like-named methods of any one class. That is to say, that you do not have to look far to see if the key is unique.
At some point in development you must create a string in the base .properties file which can then be internationalized as appropriate. The full name of the resource in the properties file is formed from the fully-qualified class name, ".", the method name, "." and this key parameter, with any spaces replaced by underscores ("_").
Until you create such a string in the properties file, the key itself will identify exceptions of this type (that's why it should be descriptive).
Note that we do not attempt to identify messages with a key involving line number. That's because line numbers vary way too much.

detailNonLocalized - This is extra information which is not localizable.

Since:

1.3 updated to allow for ':' delimiter in key

LocalizedException

public LocalizedException(java.lang.String key,
                          java.lang.Throwable cause)

Construct an exception with the key to the problem and a causal exception. The latter will be converted into a non-localizable detail message which is then passed to ctor LocalizedException(String,String)
Use this ctor when you catch an exception but you decide to throw a new exception for one or both of the following reasons:

• you wish to throw an exception of this class;
• you wish to add some more context to the detail of the exception.

For example, suppose you are managing a stack and you implement the pop method by decrementing the stack index and returning the appropriate cell. The system is likely to throw an ArrayIndexOutOfBoundsException if the index is less than zero or >= N where N is the length of the array. In the first case, you can interpret the exception in the context of your method as meaning that the stack is empty and you decide to throw an instance of a subclass of this class and which you expect your caller to be able to handle. In the other case, your caller cannot handle the problem (you didn't create the array to be large enough) and so you might decide to rethrow the original exception.
Note also that because this method utilized getStackDumpAsString(Throwable) it correctly handles the case where cause is of class java.lang.reflect.InvocationTargetException

Parameters:

key - A key to a localizable detail message.

cause - The exception which caused the problem.

Since:

1.1

See Also:

LocalizedException(String,String)

LocalizedException

public LocalizedException(java.lang.String key)

Construct an exception with the key to the problem.

Parameters:

key - A key to a localizable detail message. The key itself should be unique amongst the potential instances of this exception class.

Since:

1.1

See Also:

LocalizedException(String,String)

LocalizedException

protected LocalizedException()

You must specify either the text message. An exception with no info is close to useless, so this method is protected to avoid this kind of thing.

Since:

1.1

Method Detail

getResourceBundle

public abstract java.util.ResourceBundle getResourceBundle()

Method to get a reference to the resource bundle for this class. This method must be overridden in any concrete extender of this class.

Returns:

a resource bundle

Since:

1.1

getLocalizedMessage

public java.lang.String getLocalizedMessage()

This method is used by the toString method and indirectly by the printStackTrace methods in order to get a representation of the exception. It does not affect the stack trace, obviously.
Can generate non-localized string: "unspecified detail".
This method overrides the method in the super class

Before being looked up in the resource bundles, they key has any embedded spaces converted into underscores ("_"). Furthermore, any characters including and to the right of an equality (":") are not considered part of the resource key and are simply reattached to the localized value retrieved using the key.

Returns:

A localized representation of the exception detail message which may be null

Since:

1.3 supports the delimiter ":" which terminates the localizable key

toString

public java.lang.String toString()

Returns a short description of this throwable object. If this Throwable object was created with an error message string, then the result is the concatenation of three strings:

• The name of the actual class of this object
• ": " (a colon and a space)
• The result of the Throwable.getMessage() method for this object

If this Throwable object was java.lang.Throwable#toString()} created} with no error message string, then the name of the actual class of this object is returned.

Returns:

a string representation of this Throwable.

Since:

1.2 updated - adds the thrown-by string here instead of in getLocalizedMessage())

printStackTrace

public void printStackTrace(java.io.PrintStream s)

Prints this LocalizedException and its backtrace to the specified print stream.
This method overrides the method in the super class

Parameters:

s - The print stream to print the stack trace to

Since:

1.1

getStackDumpAsString

public static java.lang.String getStackDumpAsString(java.lang.Throwable e)

Utility method to return the current exception stack dump as a String.
Note that this method correctly extracts the details of an exception wrapped by java.lang.reflect.InvocationTargetException so no special processing for that situation is required.

Parameters:

e - The exception being handled

Returns:

A string containing the description of the exception followed by the stack dump.

Since:

1.1

getCaller

public static java.lang.String getCaller(java.lang.Throwable e,
                                         int index)
                                  throws java.lang.RuntimeException

Gets the string representing the indexth caller (stack frame) within the stack trace of an exception. The string returned is the indexth block of text which is between $StackCallPrefix and a newline.
It consists of class-method-specifier "(" location-specifier ")"
where class-method-specifier consists of: class-name "." method-name
and where location-specifier consists of: module-name ":" line-number

Parameters:

e - The exception whose stack frame we wish to extract from.

index - The index specifying which stack frame we are interested in. 0 represents the top (i.e. the actual method which threw the exception).

Returns:

The indexth caller entry (see above for format).

Throws:

com.truexchange.trumarket.System.ExceptionHandler.RuntimeException - This will be thrown if the index was incorrectly specified or if there is some other problem.

java.lang.RuntimeException

Since:

1.1

getCaller

public static java.lang.String getCaller(java.lang.Throwable e)

Get the caller details of the thrower of an exception. Calls getCaller(java.lang.Throwable,int) with index of 0.

Parameters:

e - The exception

Returns:

See getCaller(java.lang.Throwable,int) for format details. May be null.

Since:

1.1

getCallerClassMethod

public static java.lang.String getCallerClassMethod(java.lang.Throwable e)

Get the class-method part of the caller string. Calls getCaller(java.lang.Throwable) and then returns the portion in front of the "("

Parameters:

e - The exception for which we want the thrower

Returns:

The class and method names (separated by ".") of the thrower of the exception e May be null.

Since:

1.1