net.sf.mmm.util.exception.api

Class NlsException

java.lang.Object

java.lang.Throwable

java.lang.Exception

net.sf.mmm.util.exception.api.NlsException

All Implemented Interfaces:

Serializable, Cloneable, NlsThrowable, AttributeReadMessage, AttributeReadMessageCode, AttributeReadUuid, NlsObject

public abstract class NlsException
extends Exception
implements NlsThrowable, Cloneable

This is an abstract base implementation of a checked exception with real native language support (NLS).
ATTENTION:
Checked exceptions are discouraged and should be avoided. Use NlsRuntimeException instead.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

NlsThrowable, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
private NlsMessage	nlsMessage the internationalized message
private static long	serialVersionUID UID for serialization.
private UUID	uuid

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	NlsException(NlsException copySource, ExceptionTruncation truncation) The copy constructor.
	NlsException(NlsMessage message) The constructor.
	NlsException(Throwable nested, NlsMessage message) The constructor.

Method Summary

Modifier and Type	Method and Description
NlsRuntimeException	createCopy(ExceptionTruncation truncation) Returns a copy of the given exception where the specified details are removed.
protected NlsRuntimeException	createCopyViaClone(ExceptionTruncation truncation)
protected UUID	createUuid() This method creates a new UUID.
String	getCode() This method gets the code that identifies the detailed type of this object.
String	getLocalizedMessage()
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	getMessage() This method gets the actual message that describes this object.
NlsMessage	getNlsMessage() This method gets the NlsMessage describing the problem.
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, fillInStackTrace, getCause, 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

Field Detail

serialVersionUID

private static final long serialVersionUID

UID for serialization.

See Also:

Constant Field Values

nlsMessage

private final NlsMessage nlsMessage

the internationalized message

uuid

private final UUID uuid

See Also:

getUuid()

Constructor Detail

NlsException

public NlsException(NlsMessage message)

The constructor.

Parameters:

message - the message describing the problem briefly.

NlsException

public NlsException(Throwable nested,
                    NlsMessage message)

The constructor.

Parameters:

nested - is the cause of this exception.

message - the message describing the problem briefly.

NlsException

protected NlsException(NlsException copySource,
                       ExceptionTruncation truncation)

The copy constructor.

Parameters:

copySource - is the exception to copy.

truncation - is the ExceptionTruncation to configure potential truncations.

Method Detail

createUuid

protected UUID createUuid()

This method creates a new UUID.

Returns:

the new UUID or null to turn this feature off.

getUuid

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

getNlsMessage

public final NlsMessage getNlsMessage()

This method gets the NlsMessage describing the problem.

Specified by:

getNlsMessage in interface NlsThrowable

Returns:

the NlsMessage.

printStackTrace

public void printStackTrace(Locale locale,
                            Appendable buffer)

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.

createCopyViaClone

protected NlsRuntimeException createCopyViaClone(ExceptionTruncation truncation)

Parameters:

truncation - the ExceptionTruncation settings.

Returns:

the (truncated) copy.

See Also:

createCopy(ExceptionTruncation)

createCopy

public NlsRuntimeException 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. This default implementation is using clone to create a copy and truncate it as configured. However, a proper implementation would use the appropriate copy constructor instead.

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.

getMessage

public String getMessage()

This method gets the actual message that describes this object. Such message should contain contextual information to describe and track down the information, problem, warning or error. It is either technical and should help operators or developers to identify what happened or it will be information displayed to end-users and should be clear and easy to understand. For internationalization see Message and NlsMessage. In any case it should NOT contain sensitive information such as passwords or (detailed) personal data.

Specified by:

getMessage in interface AttributeReadMessage

Overrides:

getMessage in class Throwable

Returns:

the message text.

See Also:

Throwable.getMessage(), NlsThrowable, Message

getLocalizedMessage

public String getLocalizedMessage()

Overrides:

getLocalizedMessage in class Throwable

getLocalizedMessage

public String getLocalizedMessage(Locale locale)

This method gets the localized message as string.

Specified by:

getLocalizedMessage in interface NlsThrowable

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

Parameters:

locale - is the Locale to translate to.

appendable - is where to append the message to.

See Also:

NlsMessage.getLocalizedMessage(Locale, Appendable)

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.

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

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

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.