net.sf.mmm.util.nls.api
Interface NlsThrowable

All Superinterfaces:

NlsObject

All Known Implementing Classes:

AbstractNlsException, AbstractNlsRuntimeException, AccessFailedException, AlreadyInitializedException, AnnotationNotForTargetException, AnnotationNotRuntimeException, BufferExceedException, CliArgumentMissingException, CliArgumentReferenceMissingException, CliClassNoPropertyException, CliException, CliModeUndefinedException, CliOptionAndArgumentAnnotationException, CliOptionDuplicateException, CliOptionIllegalNameOrAliasException, CliOptionIncompatibleModesException, CliOptionMisplacedException, CliOptionMissingException, CliOptionMissingValueException, CliOptionUndefinedException, CliParameterListEmptyException, CliParserExcepiton, ComposedException, ContainerGrowthException, DuplicateObjectException, FileAlreadyExistsException, FileCreationFailedException, FileDeletionFailedException, FileNotExistsException, IllegalCaseException, IllegalDateFormatException, IllegalPojoPathException, IllegalWildcardSequenceException, InstantiationFailedException, InvocationFailedException, NlsClassCastException, NlsException, NlsFormatterChoiceNoElseConditionException, NlsFormatterChoiceOnlyElseConditionException, NlsIllegalArgumentException, NlsIllegalStateException, NlsNullPointerException, NlsParseException, NlsRuntimeException, NlsUnsupportedOperationException, NodeCycleException, NotInitializedException, NumberConversionException, ObjectNotFoundException, PojoPathAccessException, PojoPathCachingDisabledException, PojoPathConversionException, PojoPathCreationException, PojoPathException, PojoPathFunctionUndefinedException, PojoPathFunctionUnsupportedOperationException, PojoPathSegmentIsNullException, PojoPathUnsafeException, PojoPropertyNotFoundException, ReflectionException, ResourceAmbiguousException, ResourceMissingException, ResourceNotAvailableException, ResourceNotWritableException, ResourceUriUndefinedException, RuntimeIoException, StreamClosedException, TypeNotFoundException, UnknownCollectionInterfaceException, ValueConvertException, ValueException, ValueNotSetException, ValueOutOfRangeException, WrongValueTypeException, XmlException, XmlGenericException, XmlInvalidException

public interface NlsThrowable
extends NlsObject

This is the interface for exceptions and runtime exceptions with real native language support (NLS).
In extension to a regular throwable it brings enhanced native language support (NLS). In a server environment there can be multiple users active at a time with different locales.
This approach aims to simplify the NLS when creating throwables with error messages. It has the following principles:

• The throwable itself contains the message in English language so this is always available even if nationalization fails.
• The language independent parts of the message are separated in an argument list that is inserted into the message after nationalization.
• The throwable itself does not know the component that does the actual localization which is done by the callback interface NlsTemplateResolver.

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_DEFAULT, KEY_DIRECTORY, KEY_ERROR, 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_VALUE

Method Summary

Throwable	getCause()
String	getLocalizedMessage(Locale locale) This method gets the localized message as string.
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 string buffer.
String	getMessage()
NlsMessage	getNlsMessage() This method gets the NlsMessage describing the problem.
StackTraceElement[]	getStackTrace()
UUID	getUuid() This method gets the UUID of this exception.
void	printStackTrace(Locale locale, Appendable buffer) This method prints the stack trace with localized exception message(s).
void	printStackTrace(Locale locale, NlsTemplateResolver resolver, Appendable buffer) This method prints the stack trace with localized exception message(s).

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

toNlsMessage

Method Detail

getCause

Throwable getCause()

Returns:

the cause.

getMessage

String getMessage()

Returns:

the message.

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, NlsTemplateResolver, Appendable)

getLocalizedMessage

String getLocalizedMessage(Locale locale,
                           NlsTemplateResolver resolver)

This method gets the localized message as string.

Parameters:

locale - is the locale to translate to.

resolver - is used to resolve the template in order to translate the original i18n message.

Returns:

the localized message.

See Also:

getLocalizedMessage(Locale, NlsTemplateResolver, Appendable)

getLocalizedMessage

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

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

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 - if the given buffer produced an IOException.

See Also:

NlsMessage.getLocalizedMessage(Locale, NlsTemplateResolver, 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

printStackTrace

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

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

Parameters:

locale - is the locale to translate to.

resolver - translates the original message.

buffer - is where to write the stack trace to.

Throws:

IllegalStateException - if the given buffer produced an IOException.

getStackTrace

StackTraceElement[] getStackTrace()

Returns:

the stack-trace.

getUuid

UUID getUuid()

This method gets the UUID of this exception. The UUID is created when the exception is constructed or copied from the given cause if it is also a NlsThrowable.
The UUID will appear in the printed stacktrace but NOT in the message and should therefore be written to log-files if the NlsThrowable is logged. If you supply the UUID to the end-user in case of an unexpected error, he can easily find the stacktrace in the log-files.

Returns:

the UUID of this exception. It may be null if this feature is turned of (it is turned on by default).