net.sf.mmm.util.exception.api

Class GenericSerializableException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

net.sf.mmm.util.exception.api.GenericSerializableException

All Implemented Interfaces:

Serializable, NlsThrowable, AttributeReadMessage, AttributeReadMessageCode, AttributeReadUuid, NlsMessage, NlsObject

public class GenericSerializableException
extends RuntimeException
implements NlsThrowable, NlsMessage

This is a very specific exception that allows sending of any Throwable via a remote service. Some exceptions can not be serialized at all and others may not be de-serialized because they (or one of their causes or suppressed exceptions) are an implementation secret and are therefore not in the classpath on the other end. This exception allows to wrap any other kind of exception so the message, code, UUID and stacktrace are preserved while the other end only needs to know this exception class. However the original type of the exception is lost in the manner that catching, handling and instanceof-checks of the actual exception will not work anymore.

Since:

4.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
private String	code
private String	originalExceptionName
private static long	serialVersionUID UID for serialization.
private boolean	technical
private UUID	uuid

Fields inherited from interface net.sf.mmm.util.nls.api.NlsMessage

LOCALIZATION_FAILURE_PREFIX

Fields inherited from interface net.sf.mmm.util.nls.api.NlsObject

KEY_ANNOTATION, KEY_ARGUMENT, KEY_CAPACITY, KEY_CONTAINER, KEY_DEFAULT, KEY_DIRECTORY, KEY_ERROR, KEY_EXISTING, KEY_EXPECTED, KEY_FILE, KEY_FUNCTION, KEY_ID, KEY_KEY, KEY_LOCATION, KEY_MAX, KEY_MIN, KEY_MODE, KEY_NAME, KEY_OBJECT, KEY_OPERAND, KEY_OPERATION, KEY_OPTION, KEY_PATH, KEY_PROPERTY, KEY_QUERY, KEY_RESOURCE, KEY_SIZE, KEY_SOURCE, KEY_TARGET_TYPE, KEY_TITLE, KEY_TYPE, KEY_URI, KEY_USER, KEY_VALUE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	GenericSerializableException() The constructor for de-serialization in GWT.
	GenericSerializableException(Throwable cause, String message, String originalExceptionName, StackTraceElement[] stacktrace, boolean technical, String code, UUID uuid) The constructor.

Method Summary

Modifier and Type	Method and Description
GenericSerializableException	createCopy(ExceptionTruncation truncation) Returns a copy of the given exception where the specified details are removed.
Throwable	fillInStackTrace() Prevents creating a stacktrace.
Object	getArgument(int index) This method gets the language independent argument at the given index.
Object	getArgument(String key) This method gets the language independent argument for the given key.
int	getArgumentCount() This method gets the number of language independent arguments of this exception.
String	getCode() This method gets the code that identifies the detailed type of this object.
String	getInternationalizedMessage() This method gets the internationalized message that can be translated to a native language.
String	getLocalizedMessage(Locale locale) This method gets the localized message as string.
void	getLocalizedMessage(Locale locale, Appendable appendable) This method writes the localized message to the given string buffer.
String	getLocalizedMessage(Locale locale, NlsTemplateResolver resolver) This method gets the localized message as string.
void	getLocalizedMessage(Locale locale, NlsTemplateResolver resolver, Appendable buffer) This method writes the localized message to the given buffer.
NlsMessage	getNlsMessage() This method gets the NlsMessage describing the problem.
String	getOriginalExceptionName()
UUID	getUuid() This method gets the UUID of this object.
boolean	isForUser()
boolean	isTechnical() Determines if this is a technical exception.
void	printStackTrace(Locale locale, Appendable buffer) This method prints the stack trace with localized exception message(s).
NlsMessage	toNlsMessage() This method is the equivalent to Object.toString() with native language support.
String	toString()
String	toString(Locale locale) Like NlsThrowable.toString() but using the specified Locale.
Appendable	toString(Locale locale, Appendable appendable) appends the localized string representation of this exception.

Methods inherited from class java.lang.Throwable

addSuppressed, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.mmm.util.exception.api.NlsThrowable

getCause, getStackTrace

Methods inherited from interface net.sf.mmm.util.lang.api.attribute.AttributeReadMessage

getMessage

Methods inherited from interface net.sf.mmm.util.nls.api.NlsMessage

getLocalizedMessage, getMessage

Field Detail

serialVersionUID

private static final long serialVersionUID

UID for serialization.

See Also:

Constant Field Values

originalExceptionName

private String originalExceptionName

See Also:

getOriginalExceptionName()

code

private String code

See Also:

getCode()

technical

private boolean technical

See Also:

isTechnical()

uuid

private UUID uuid

See Also:

getUuid()

Constructor Detail

GenericSerializableException

protected GenericSerializableException()

The constructor for de-serialization in GWT.

GenericSerializableException

public GenericSerializableException(Throwable cause,
                                    String message,
                                    String originalExceptionName,
                                    StackTraceElement[] stacktrace,
                                    boolean technical,
                                    String code,
                                    UUID uuid)

The constructor.

Parameters:

cause - - see Throwable.getCause(). Should be a GenericSerializableException.

message - - see Throwable.getMessage().

originalExceptionName - - see getOriginalExceptionName().

stacktrace - - the stacktrace of the original exception.

technical - - see isTechnical().

code - - see getCode().

uuid - - see getUuid().

Method Detail

createCopy

public GenericSerializableException createCopy(ExceptionTruncation truncation)

Returns a copy of the given exception where the specified details are removed. See ExceptionUtil for advanced usage and further details.
NOTE:
Implementations/subclasses can override the return type with the subclass. As Java does not support an implicit SELF generic and we do not want to overload all exceptions with a generic type.

Specified by:

createCopy in interface NlsThrowable

Parameters:

truncation - the ExceptionTruncation to configure what to remove. E.g. ExceptionTruncation.REMOVE_ALL.

Returns:

a truncated copy of this exception.

getOriginalExceptionName

public String getOriginalExceptionName()

Returns:

the originalExceptionName

fillInStackTrace

public Throwable fillInStackTrace()

Prevents creating a stacktrace.

Overrides:

fillInStackTrace in class Throwable

Returns:

this instance.

getCode

public String getCode()

This method gets the code that identifies the detailed type of this object. While UUID or ID are typically unique per instance of an object the code is unique for all instances of the exact same kind. So e.g. a particular kind of exception or ValidationFailure can be identified by its code. A simple generic implementation may return the classname or the key of the NLS message. However, the code should remain stable after refactoring (so at least after the rename the previous code should be returned as String literal). This code may be used as a compact identifier to reference the related problem or information as well as for automatic tests of error situations that should remain stable even if the message text gets improved or the locale is unknown.

Specified by:

getCode in interface AttributeReadMessageCode

Returns:

the message text.

See Also:

Throwable.getMessage(), NlsThrowable, Message

getUuid

public UUID getUuid()

This method gets the UUID of this object. When the object is created, a UUID is generated. In case the object is created from another object that already has a UUID, the existing UUID will be used (e.g. for chained exceptions).
The UUID will appear in a stacktrace but NOT in the message. It will therefore be written to log-files if the NlsThrowable is logged. If you supply the UUID to the end-user in an error panel or popup (see Message), he can provide it with the problem report so an administrator or software developer can easily find the stacktrace in the log-files.

Specified by:

getUuid in interface AttributeReadUuid

Returns:

the UUID of this object. It may be null if this feature is NOT supported by the type of this object or turned of (it is turned on by default).

toNlsMessage

public NlsMessage toNlsMessage()

This method is the equivalent to Object.toString() with native language support.

Specified by:

toNlsMessage in interface NlsObject

Returns:

an nls message representing this object.

getInternationalizedMessage

public String getInternationalizedMessage()

This method gets the internationalized message that can be translated to a native language. The language independent arguments are filled into the message after the translation process.
E.g. the i18n message may be "Welcome {name}!" and there is one argument that is the string "Joelle". The final result will then be "Welcome Joelle!". If the message is translated to German as "Willkommen {name}!" the final result will be "Willkommen Joelle!".

Specified by:

getInternationalizedMessage in interface NlsMessage

Returns:

the message for internationalization.

See Also:

NlsMessage, NlsMessage.getArgument(String), MessageFormat

getArgumentCount

public int getArgumentCount()

This method gets the number of language independent arguments of this exception.

Specified by:

getArgumentCount in interface NlsMessage

Returns:

the argument count.

getArgument

public Object getArgument(String key)

This method gets the language independent argument for the given key.

Specified by:

getArgument in interface NlsMessage

Parameters:

key - is the name of the requested argument.

Returns:

the argument for the given key or null if NOT defined.

getArgument

public Object getArgument(int index)

This method gets the language independent argument at the given index.

Specified by:

getArgument in interface NlsMessage

Parameters:

index - is the index of the requested argument.

Returns:

the argument for the given key.

isTechnical

public boolean isTechnical()

Determines if this is a technical exception.

• A technical exception is an unexpected situation that is to be logged on error level and should be analyzed by the operators or software developers of the system. Further in such case the end-user can typically do nothing about the problem (except to retry his operation) and will typically not understand the problem. Therefore a generic message should be displayed to the end-user in such case. See TechnicalErrorUserException.
• A non technical exception is called user failure. It is an undesired but NOT abnormal situation. It should be logged on a level less than error (typically info). The message is typically intended for to end-users and has to be easy to understand.

This separation is intentionally not done via inheritance of technical and business exception base classes to allow reuse. However, if you want to have it this way, create such classes derived from NlsRuntimeException.

Specified by:

isTechnical in interface NlsThrowable

Returns:

true if this is a technical exception, false if this is a user error.

See Also:

NlsThrowable.isForUser()

isForUser

public boolean isForUser()

Specified by:

isForUser in interface NlsThrowable

Returns:

true if the message of this exception is for end-users (or clients), false otherwise (for internal technical errors).

getNlsMessage

public NlsMessage getNlsMessage()

This method gets the NlsMessage describing the problem.

Specified by:

getNlsMessage in interface NlsThrowable

Returns:

the NlsMessage.

getLocalizedMessage

public String getLocalizedMessage(Locale locale)

This method gets the localized message as string.

Specified by:

getLocalizedMessage in interface NlsThrowable

Specified by:

getLocalizedMessage in interface NlsMessage

Parameters:

locale - is the Locale to translate to.

Returns:

the localized message.

See Also:

NlsThrowable.getLocalizedMessage(Locale, Appendable)

getLocalizedMessage

public void getLocalizedMessage(Locale locale,
                                Appendable appendable)

This method writes the localized message to the given string buffer.

Specified by:

getLocalizedMessage in interface NlsThrowable

Specified by:

getLocalizedMessage in interface NlsMessage

Parameters:

locale - is the Locale to translate to.

appendable - is where to append the message to.

See Also:

NlsMessage.getLocalizedMessage(Locale, Appendable)

getLocalizedMessage

public String getLocalizedMessage(Locale locale,
                                  NlsTemplateResolver resolver)

This method gets the localized message as string.

Specified by:

getLocalizedMessage in interface NlsMessage

Parameters:

locale - is the locale to translate to.

resolver - is used to translate the message.

Returns:

the localized message.

See Also:

NlsMessage.getLocalizedMessage(Locale, NlsTemplateResolver, Appendable)

getLocalizedMessage

public void getLocalizedMessage(Locale locale,
                                NlsTemplateResolver resolver,
                                Appendable buffer)
                         throws IllegalStateException

This method writes the localized message to the given buffer.
The actual localization is done by a template that is provided via the given resolver. If this fails, the original message will be used. After translation is done, the language independent arguments will be filled in the translated message string according to the given locale.

Specified by:

getLocalizedMessage in interface NlsMessage

Parameters:

locale - is the locale to translate to.

resolver - is used to resolve the template required to translate the internationalized message.

buffer - is the buffer where to write the message to.

Throws:

IllegalStateException

printStackTrace

public void printStackTrace(Locale locale,
                            Appendable buffer)
                     throws IllegalStateException

This method prints the stack trace with localized exception message(s).

Specified by:

printStackTrace in interface NlsThrowable

Parameters:

locale - is the locale to translate to.

buffer - is where to write the stack trace to.

Throws:

IllegalStateException - if the given buffer produced an IOException.

toString

public String toString()

Specified by:

toString in interface NlsThrowable

Overrides:

toString in class Throwable

See Also:

NlsThrowable.toString(Locale)

toString

public String toString(Locale locale)

Like NlsThrowable.toString() but using the specified Locale.

Specified by:

toString in interface NlsThrowable

Parameters:

locale - is the Locale used for NlsThrowable.getLocalizedMessage(Locale).

Returns:

the localized string representation of this exception as described in NlsThrowable.toString(Locale, Appendable).

toString

public Appendable toString(Locale locale,
                           Appendable appendable)

appends the localized string representation of this exception. It is defined as following:

<classname>: [<custom-code>: ]<message>

Specified by:

toString in interface NlsThrowable

Parameters:

locale - is the Locale used for NlsThrowable.getLocalizedMessage(Locale).

appendable - is the buffer to append to. Will be created as StringBuilder if null is provided.

Returns:

the provided Appendable or the created one if null was given.