hirondelle.web4j.model
Class AppResponseMessage

Object
  hirondelle.web4j.model.AppResponseMessage

All Implemented Interfaces:

Serializable

public final class AppResponseMessage
extends Object
implements Serializable

Informative message presented to the end user.

This class exists in order to hide the difference between simple and compound messages.

Simple Messages
Simple messages are a single String, such as 'Item deleted successfully.'. They are created using forSimple(String).

Compound Messages
Compound messages are made up of several parts, and have parameters. They are created using forCompound(String, Object...). A compound message is usually implemented in Java using MessageFormat. However, MessageFormat is not used by this class, to avoid the following issues :

• the dreaded apostrophe problem. In MessageFormat, the apostrophe is a special character, and must be escaped. This is highly unnatural for translators, and has been a source of continual, bothersome errors. (This is the principal reason for not using MessageFormat.)
• the {0} placeholders start at 0, not 1. Again, this is unnatural for translators.
• the number of parameters cannot exceed 10. (Granted, it is not often that a large number of parameters are needed, but there is no reason why this restriction should exist.)
• in general, MessageFormat is rather complicated in its details.

Format of Compound Messages
This class defines an alternative format to that defined by MessageFormat. For example,

  "At this restaurant, the _1_ meal costs _2_."
  "On _2_, I am going to Manon's place to see _1_."
 

Here,

• the placeholders appear as _1_, _2_, and so on. They start at 1, not 0, and have no upper limit. There is no escaping mechanism to allow the placeholder text to appear in the message 'as is'. The _i_ placeholders stand for an Object, and carry no format information.
• apostrophes can appear anywhere, and do not need to be escaped.
• the formats applied to the various parameters are taken from Formats. If the default formatting applied by Formats is not desired, then the caller can always manually format the parameter as a String. (The Translator may be used when a different pattern is needed for different Locales.)
• the number of parameters passed at runtime must match exactly the number of _i_ placeholders

Multilingual Applications
Multilingual applications will need to ensure that messages can be successfully translated when presented in JSPs. In particular, some care must be exercised to not create a simple message out of various pieces of data when a compound message should be used instead. See getMessage(Locale, TimeZone). As well, see the hirondelle.web4j.ui.translate package for more information, in particular the Messages tag used for rendering AppResponseMessages, even in single language applications.

Serialization
This class implements Serializable to allow messages stored in session scope to be transferred over a network, and thus survive a failover operation. However, this class's implementation of Serializable interface has a minor defect. This class accepts Objects as parameters to messages. These objects almost always represent data - String, Integer, Id, DateTime, and so on, and all such building block classes are Serializable. If, however, the caller passes an unusual message parameter object which is not Serializable, then the serialization of this object (if it occurs), will fail.

The above defect will likely not be fixed since it has large ripple effects, and would seem to cause more problems than it would solve. In retrospect, this the message parameters passed to forCompound(String, Object[]) should likely have been typed as Serializable, not Object.

See Also:

Serialized Form

Method Summary

boolean	equals(Object aThat)
static AppResponseMessage	forCompound(String aPattern, Object... aParams) Compound message having parameters.
static AppResponseMessage	forSimple(String aSimpleText) Simple message having no parameters.
String	getMessage(Locale aLocale, TimeZone aTimeZone) Return either the 'simple text' or the formatted pattern with all parameter data rendered, according to which factory method was called.
List<Object>	getParams() Return an unmodifiable List corresponding to the aParams passed to the constructor.
int	hashCode()
String	toString() Return either the 'simple text' or the pattern, according to which factory method was called.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

forSimple

public static AppResponseMessage forSimple(String aSimpleText)

Simple message having no parameters. aSimpleText must have content.

forCompound

public static AppResponseMessage forCompound(String aPattern,
                                             Object... aParams)

Compound message having parameters.

aPattern follows the custom format defined by this class. Formats.objectToTextForReport(java.lang.Object) will be used to format all parameters.

Parameters:

aPattern - must be in the style of the custom format, and the number of placeholders must match the number of items in aParams.

aParams - must have at least one member; all members must be non-null, but may be empty Strings.

getMessage

public String getMessage(Locale aLocale,
                         TimeZone aTimeZone)

Return either the 'simple text' or the formatted pattern with all parameter data rendered, according to which factory method was called.

The configured Translator is used to localize

• the text passed to forSimple(String)
• the pattern passed to forCompound(String, Object...)
• any RequestParameter parameters passed to forCompound(String, Object...) are localized by using Translator on the return value of RequestParameter.getName() (This is intended for displaying localized versions of control names.)

It is highly recommended that this method be called late in processing, in a JSP.

The Locale should almost always come from BuildImpl.forLocaleSource(). The aLocale parameter is always required, even though there are cases when it is not actually used to render the result.

getParams

public List<Object> getParams()

Return an unmodifiable List corresponding to the aParams passed to the constructor.

If no parameters are being used, then return an empty list.

toString

public String toString()

Return either the 'simple text' or the pattern, according to which factory method was called. Typically, this method is not used to present text to the user (see getMessage(java.util.Locale, java.util.TimeZone)).

Overrides:

toString in class Object

equals

public boolean equals(Object aThat)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object