net.sf.mmm.util.exception.api

Class NlsRuntimeException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

net.sf.mmm.util.exception.api.NlsRuntimeException

All Implemented Interfaces:

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

Direct Known Subclasses:

AlreadyInitializedException, BufferExceedException, BusinessErrorUserException, CliException, ComposedException, ContainerGrowthException, DuplicateObjectException, IllegalCaseException, IllegalDateFormatException, IllegalWildcardSequenceException, NlsClassCastException, NlsFormatterChoiceNoElseConditionException, NlsFormatterChoiceOnlyElseConditionException, NlsIllegalArgumentException, NlsIllegalStateException, NlsNullPointerException, NlsParseException, NlsRuntimeWrapperException, NlsUnsupportedOperationException, NodeCycleException, NotInitializedException, NumberConversionException, ObjectDisposedException, ObjectMismatchException, ObjectNotFoundException, OptimisticLockingException, PojoPathException, PojoPropertyNotFoundException, ReadOnlyException, ReflectionException, RemoteInvocationCallFailedException, ResourceAmbiguousException, ResourceMissingException, ResourceNotAvailableException, ResourceNotWritableException, ResourceUriUndefinedException, RuntimeIoException, SearchException, SearchTimeoutException, SecurityErrorUserException, StreamClosedException, TechnicalErrorUserException, TransactionCommitException, TransactionNotActiveException, TransactionRollbackException, UnknownCollectionInterfaceException, ValidationErrorUserException, ValidationErrorUserException, ValueException, ValueException, XmlException, XmlParseException

public abstract class NlsRuntimeException
extends RuntimeException
implements NlsThrowable, Cloneable

This is an abstract base implementation of NlsThrowable based on RuntimeException. For further details see NlsThrowable. For an example read the package javadoc or see the source code of the derived exceptions.

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
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	NlsRuntimeException() The constructor for de-serialization in GWT.
	NlsRuntimeException(NlsMessage message) The constructor.
protected	NlsRuntimeException(NlsRuntimeException copySource, ExceptionTruncation truncation) The copy constructor.
	NlsRuntimeException(String internationalizedMessage) The constructor.
	NlsRuntimeException(Throwable cause, NlsMessage message) The constructor.
	NlsRuntimeException(Throwable cause, String internationalizedMessage) The constructor.

Method Summary

Modifier and Type	Method and Description
protected static <BUNDLE extends NlsBundle> BUNDLE	createBundle(Class<BUNDLE> bundleInterface)
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).
(package private) static void	printStackTrace(NlsThrowable throwable, Locale locale, Appendable buffer)
private static void	printStackTraceCause(Throwable cause, Locale locale, Appendable buffer)
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

See Also:

Constant Field Values

nlsMessage

private NlsMessage nlsMessage

the internationalized message

uuid

private UUID uuid

Constructor Detail

NlsRuntimeException

protected NlsRuntimeException()

The constructor for de-serialization in GWT.

NlsRuntimeException

public NlsRuntimeException(NlsMessage message)

The constructor.

Parameters:

message - the message describing the problem briefly.

NlsRuntimeException

public NlsRuntimeException(String internationalizedMessage)

The constructor.
ATTENTION:
Please use NlsRuntimeException(NlsMessage) in advance to this constructor to get best NLS/I18N.

Parameters:

internationalizedMessage - is a short description of the problem. It is used for internationalization and should be in English language.

NlsRuntimeException

public NlsRuntimeException(Throwable cause,
                           String internationalizedMessage)

The constructor.
ATTENTION:
Please use NlsRuntimeException(Throwable, NlsMessage) in advance to this constructor to get best NLS/I18N.

Parameters:

cause - is the cause of this exception.

internationalizedMessage - is a short description of the problem. It is used for internationalization and should be in English language.

NlsRuntimeException

public NlsRuntimeException(Throwable cause,
                           NlsMessage message)

The constructor.

Parameters:

cause - is the cause of this exception.

message - the message describing the problem briefly.

NlsRuntimeException

protected NlsRuntimeException(NlsRuntimeException 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()

Description copied from interface: AttributeReadUuid

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

Description copied from interface: NlsThrowable

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)

Description copied from interface: NlsThrowable

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.

printStackTrace

static void printStackTrace(NlsThrowable throwable,
                            Locale locale,
                            Appendable buffer)

Parameters:

throwable - is the NlsThrowable to print.

locale - is the Locale to translate to.

buffer - is where to write the stack trace to.

See Also:

NlsThrowable.printStackTrace(Locale, Appendable)

printStackTraceCause

private static void printStackTraceCause(Throwable cause,
                                         Locale locale,
                                         Appendable buffer)
                                  throws IOException

Parameters:

cause - is the Throwable to print.

locale - is the Locale to translate to.

buffer - is where to write the stack trace to.

Throws:

IOException - if caused by buffer.

See Also:

NlsThrowable.printStackTrace(Locale, Appendable)

getMessage

public String getMessage()

Description copied from interface: AttributeReadMessage

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)

Description copied from interface: NlsThrowable

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)

Description copied from interface: NlsThrowable

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

Description copied from interface: NlsObject

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.

createBundle

protected static <BUNDLE extends NlsBundle> BUNDLE createBundle(Class<BUNDLE> bundleInterface)

Type Parameters:

BUNDLE - is the generic type of the requested NlsBundle.

Parameters:

bundleInterface - is the NlsBundle interface.

Returns:

the NlsBundle instance.

See Also:

NlsBundleFactory.createBundle(Class)

isTechnical

public boolean isTechnical()

Description copied from interface: NlsThrowable

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

Description copied from interface: AttributeReadMessageCode

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

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.

toString

public String toString()

Description copied from interface: NlsThrowable

Specified by:

toString in interface NlsThrowable

Overrides:

toString in class Throwable

See Also:

NlsThrowable.toString(Locale)

toString

public String toString(Locale locale)

Description copied from interface: NlsThrowable

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)

Description copied from interface: NlsThrowable

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.