net.sf.mmm.util.exception.api

Interface NlsThrowable

All Superinterfaces:

AttributeReadMessage, AttributeReadMessageCode, AttributeReadUuid, NlsObject, Serializable

All Known Implementing Classes:

AccessFailedException, AlreadyInitializedException, AnnotationNotForTargetException, AnnotationNotRuntimeException, BufferExceedException, BusinessErrorUserException, CliArgumentMissingException, CliArgumentReferenceMissingException, CliClassNoPropertyException, CliException, CliModeUndefinedException, CliOptionAndArgumentAnnotationException, CliOptionDuplicateException, CliOptionIllegalNameOrAliasException, CliOptionIncompatibleModesException, CliOptionMisplacedException, CliOptionMissingException, CliOptionMissingValueException, CliOptionUndefinedException, CliParameterListEmptyException, CliParserExcepiton, ComposedException, ContainerGrowthException, DuplicateObjectException, DuplicateObjectUserException, FileAlreadyExistsException, FileAttributeModificationFailedException, FileCreationFailedException, FileDeletionFailedException, FileNotExistsException, GenericSerializableException, IllegalCaseException, IllegalDateFormatException, IllegalPojoPathException, IllegalWildcardSequenceException, InstantiationFailedException, InvocationFailedException, NlsClassCastException, NlsException, NlsFormatterChoiceNoElseConditionException, NlsFormatterChoiceOnlyElseConditionException, NlsIllegalArgumentException, NlsIllegalStateException, NlsNullPointerException, NlsParseException, NlsRuntimeException, NlsRuntimeWrapperException, NlsUnsupportedOperationException, NodeCycleException, NotInitializedException, NumberConversionException, ObjectDisposedException, ObjectMismatchException, ObjectNotFoundException, ObjectNotFoundUserException, OptimisticLockingException, OptimisticLockingExceptionHibernate, OptimisticLockingExceptionJpa, OptimisticLockingExceptionSpring, PojoPathAccessException, PojoPathCachingDisabledException, PojoPathConversionException, PojoPathCreationException, PojoPathException, PojoPathSegmentIsNullException, PojoPathUnsafeException, PojoPropertyNotFoundException, ReadOnlyException, ReflectionException, RemoteInvocationCallFailedException, ResourceAmbiguousException, ResourceMissingException, ResourceNotAvailableException, ResourceNotWritableException, ResourceUriUndefinedException, RuntimeIoException, SearchAddFailedException, SearchEntryIdImmutableException, SearchException, SearchQueryParseException, SearchRemoveFailedException, SearchTimeoutException, SearchUpdateMissingIdException, SecurityErrorUserException, StreamClosedException, TechnicalErrorUserException, TransactionCommitException, TransactionNotActiveException, TransactionRollbackException, TypeNotFoundException, UnknownCollectionInterfaceException, ValidationErrorUserException, ValidationErrorUserException, ValueConvertException, ValueConvertException, ValueException, ValueException, ValueNotSetException, ValueNotSetException, ValueOutOfRangeException, ValueOutOfRangeException, WrongValueTypeException, WrongValueTypeException, XmlException, XmlGenericException, XmlInvalidException, XmlParseException

public interface NlsThrowable
extends NlsObject, AttributeReadUuid, AttributeReadMessage, AttributeReadMessageCode, Serializable

This is the interface for exceptions with the following features:

• real native language support via NlsMessage.
• a UUID unique per exception instance automatically generated once per exception chain.
• an error code that should be unique per exception type.
• distinguish between technical exceptions and exceptions intended for end-users.
• support for copying and truncation of the exception.

NOTE:
Exceptions should only occur in unexpected or un-normal situations. Never use exceptions for control flows.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

NlsMessage, NlsException, NlsRuntimeException

Field Summary

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

Method Summary

Modifier and Type	Method and Description
Throwable	createCopy(ExceptionTruncation truncation) Returns a copy of the given exception where the specified details are removed.
Throwable	getCause()
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.
NlsMessage	getNlsMessage() This method gets the NlsMessage describing the problem.
StackTraceElement[]	getStackTrace()
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).
String	toString()
String	toString(Locale locale) Like toString() but using the specified Locale.
Appendable	toString(Locale locale, Appendable appendable) appends the localized string representation of this exception.

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

toNlsMessage

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

getUuid

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

getMessage

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

getCode

Method Detail

getCause

Throwable getCause()

Returns:

the cause.

isTechnical

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.

Returns:

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

See Also:

isForUser()

isForUser

boolean isForUser()

Returns:

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

getNlsMessage

NlsMessage getNlsMessage()

This method gets the NlsMessage describing the problem.

Returns:

the NlsMessage.

getLocalizedMessage

String getLocalizedMessage(Locale locale)

This method gets the localized message as string.

Parameters:

locale - is the Locale to translate to.

Returns:

the localized message.

See Also:

getLocalizedMessage(Locale, Appendable)

getLocalizedMessage

void getLocalizedMessage(Locale locale,
                         Appendable appendable)

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

Parameters:

locale - is the Locale to translate to.

appendable - is where to append the message to.

See Also:

NlsMessage.getLocalizedMessage(Locale, Appendable)

printStackTrace

void printStackTrace(Locale locale,
                     Appendable buffer)
              throws IllegalStateException

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

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.

Since:

2.0.0

getStackTrace

StackTraceElement[] getStackTrace()

Returns:

the stack-trace.

createCopy

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

Parameters:

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

Returns:

a truncated copy of this exception.

toString

String toString()

Overrides:

toString in class Object

See Also:

toString(Locale)

toString

String toString(Locale locale)

Like toString() but using the specified Locale.

Parameters:

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

Returns:

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

Since:

6.0.0

toString

Appendable toString(Locale locale,
                    Appendable appendable)

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

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

Parameters:

locale - is the Locale used for 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.

Since:

6.0.0