org.moyoman.framework
Class Message

java.lang.Object
  |
  +--org.moyoman.framework.Message

public class Message

extends Object

This class is responsible for the internationalization of messages. The developer should never hard code messages which the user might see, but use symbols which are then looked up by this class. It is also used for saving new symbols, or translations of symbols. All supported languages should have the exact same number of messages. The names of all of them should be the same across languages. The names are used in the Java source and are not seen by the user. Only the values are seen by the user.

This class is not used directly to create a translation, but rather the MessageTool class is used for that purpose, and it uses this class.

To create a new translation, call one of the create() methods using the ISO standard language and country codes. This will create a Message object with the default values for all of the symbols. Using repeated calls to setMessage() will accomplish the translation.

Field Summary

private String	countryName The name of the country using ISO 3166.
private static String	defaultDisplayableName The displayable message name of the default language, e.g, U.S.
private static Message	defaultLanguage This is the Message object for the default language.
private static String	defaultSymbolicName The symbolic name of the default language, e.g, en_US.
private static HashMap	games The name is a GameId object, and the value is a Message object.
private boolean	isDefault Indicates if this is the Message object for the default language.
private String	languageName The name of the language using ISO 639.
private static HashMap	languages The name is the ISO standard name, and the value is a Message object.
private String	languageSymbolicName The symbolic message name, e.g, en_US.
private static String	messageDir The directory name where the message files are kept.
private HashMap	messages Contains the messages for the language.
(package private) Message[]	orderedAlternativeMessages This array contains the ordered alternate Message objects that can be used instead of this one.
private static String	prefix The string that all message file names start with.
private static String	suffix The string that all message file names end with.
private static HashMap	values The name is the language specific name for a language, and the value is the symbolic name, e.g, en_US.

Constructor Summary

private	Message(String symbolicName, boolean def) Create a Message object for the specified language.
protected	Message(String symbolicName, String displayableName, boolean def) Create a Message object for the specified language.

Method Summary

static void	associate(GameId id) Associate a game with the default language.
static void	associate(GameId id, String lang) Associate the game with the specified language.
static Message	create(String symbolicName, String displayableName) Create a Message object for a language.
static Message	create(String symbolicLanguageName, String symbolicCountryName, String displayableName) Create a Message object for a new language.
private static void	createMessageObjectFromFile(String fname, boolean flag) Create a Message object from the message file.
private void	defineOrderedAlternatives() Set the orderedAlternativeMessages variable.
boolean	equals(Object o) Test this object for equality with another one.
static String[]	getAllMessageTypes() Get all of the symbolic message names.
static String	getDefaultLanguageDisplayableName() Get the displayable name of the default language.
static String	getDefaultLanguageSymbolicName() Get the symbolic name of the default language.
protected static Message	getDefaultMessageObject() Get the Message object for the default language.
static String[]	getDisplayableLanguageNames() Displayable names for all supportable languages, in the local language.
protected static String	getExactMessage(String symbolicLanguageName, String symbolicMessageName) Get a message in the specified language.
private String	getLangMessage(String symbolicMessageName) Get the specified message.
static String	getMessage(GameId id, String symbolicMessageName) Get a message in the language associated with the game id.
static String	getMessage(String symbolicMessageName) Get a message in the default language.
static String	getMessage(String symbolicLanguageName, String symbolicMessageName) Get a message in the specified language.
protected static Message	getMessageObject(String symbolicLanguageName) Get the appropriate Message object.
static String	getSymbolicLanguageName(String dispLangName) Get the symbolic language name for the displayable name.
static String[]	getSymbolicLanguageNames() Symbolic names for all supportable languages, in the local language.
int	hashCode() Get a hash code for this object.
void	removeMessage(String symbolicMessageName) Remove the given symbol.
protected void	reset() Restore the Message object to the values in the messages file.
void	save() Save the results of creating or updating a language.
void	setMessage(String symbolicMessageName, String value) Set a new message for the given symbol.

Methods inherited from class java.lang.Object

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

Field Detail

games

private static HashMap games

The name is a GameId object, and the value is a Message object.

languages

private static HashMap languages

The name is the ISO standard name, and the value is a Message object.

defaultLanguage

private static Message defaultLanguage

This is the Message object for the default language.

defaultSymbolicName

private static String defaultSymbolicName

The symbolic name of the default language, e.g, en_US.

defaultDisplayableName

private static String defaultDisplayableName

The displayable message name of the default language, e.g, U.S. English

isDefault

private boolean isDefault

Indicates if this is the Message object for the default language.

values

private static HashMap values

The name is the language specific name for a language, and the value is the symbolic name, e.g, en_US.

messages

private HashMap messages

Contains the messages for the language.

languageSymbolicName

private String languageSymbolicName

The symbolic message name, e.g, en_US.

languageName

private String languageName

The name of the language using ISO 639.

countryName

private String countryName

The name of the country using ISO 3166. May be null.

messageDir

private static String messageDir

The directory name where the message files are kept.

prefix

private static final String prefix

The string that all message file names start with.

suffix

private static final String suffix

The string that all message file names end with.

orderedAlternativeMessages

Message[] orderedAlternativeMessages

This array contains the ordered alternate Message objects that can be used instead of this one.

Constructor Detail

Message

protected Message(String symbolicName,
                  String displayableName,
                  boolean def)

Create a Message object for the specified language.

Parameters:

symbolicName - This is either an ISO 639 language name, or a string of the form: ISO 639 language name, _ ISO 3166 country name, e.g, es, en_GB.

displayableName - - The language name in displayable format. This string can contain any unicode characters.

def - If true, then this is the default language.

Message

private Message(String symbolicName,
                boolean def)

Create a Message object for the specified language.

Parameters:

symbolicName - This is either an ISO 639 language name, or a string of the form: ISO 639 language name, _ ISO 3166 country name, e.g, es, en_GB.

def - If true, then this is the default language.

Method Detail

createMessageObjectFromFile

private static void createMessageObjectFromFile(String fname,
                                                boolean flag)
                                         throws InternalErrorException

Create a Message object from the message file.

Parameters:

flag - Indicates if this is the default object.

Throws:

InternalErrorException - Thrown if the operation fails for any reason.

defineOrderedAlternatives

private void defineOrderedAlternatives()

Set the orderedAlternativeMessages variable. This array contains Message objects that can be used instead of this one if getMessage() is passed a name that is not set for this language. The array is ordered, so that first element 0 is tested, then element 1, and so on until an object is found where the message name is set.

The following algorithm is used for ordering Message objects:

1. If a country code is specified, use the Message object with the same language name, but no country name.
2. Use Message objects with the same language name, but different country names.
3. Use the default Message object.

associate

public static void associate(GameId id)

Associate a game with the default language.

Parameters:

id - The GameId object.

associate

public static void associate(GameId id,
                             String lang)
                      throws NoSuchDataException

Associate the game with the specified language.

Parameters:

id - The GameId object.

lang - The symbolic name of the language to be associated with the game.

Throws:

NoSuchDataException - Thrown if the language name is unknown.

create

public static Message create(String symbolicName,
                             String displayableName)
                      throws DataAlreadyExistsException,
                             InternalErrorException

Create a Message object for a language.

Parameters:

symbolicName - The new language, using ISO-639, and optionally ISO-3166.

displayableName - The displayable name of the language.

Throws:

DataAlreadyExistsException - Thrown if the Message object for this language already exists.

InternalErrorException - Thrown if an error occurs for any reason.

create

public static Message create(String symbolicLanguageName,
                             String symbolicCountryName,
                             String displayableName)
                      throws DataAlreadyExistsException,
                             InternalErrorException

Create a Message object for a new language. Use the existing language file if it exists. Otherwise, create a new one.

Throws:

DataAlreadyExistsException - Thrown if the Message object for this language already exists.

InternalErrorException - Thrown if an error occurs for any reason.

getMessage

public static String getMessage(String symbolicLanguageName,
                                String symbolicMessageName)

Get a message in the specified language. If the message is not present in the language, then check related languages, and the default language. If all else fails, return the symbol name.

Parameters:

symbolicLanguageName - The name of the language to use.

symbolicMessageName - The symbolic name of the message.

Returns:

The message in the specified language.

getExactMessage

protected static String getExactMessage(String symbolicLanguageName,
                                        String symbolicMessageName)
                                 throws NoSuchDataException

Get a message in the specified language. If the message is not present in the specified language, then throw an exception.

Parameters:

symbolicLanguageName - The name of the language to use.

symbolicMessageName - The symbolic name of the message.

Returns:

The message in the specified language.

Throws:

NoSuchDataException - Thrown if there is no message for the symbol name.

getMessageObject

protected static Message getMessageObject(String symbolicLanguageName)
                                   throws NoSuchDataException

Get the appropriate Message object.

Parameters:

symbolicLanguageName - The symbolic name of the language to get.

Returns:

A Message object.

Throws:

NoSuchDataException - Thrown if there is no Message object for that language name.

getAllMessageTypes

public static String[] getAllMessageTypes()

Get all of the symbolic message names.

Returns:

An array of String objects.

getMessage

public static String getMessage(String symbolicMessageName)
                         throws NoSuchDataException

Get a message in the default language.

Parameters:

symbolicMessageName - The symbolic name of the message.

Returns:

The message in the specified language.

Throws:

NoSuchDataException - Thrown if there is no message for the symbol name.

getMessage

public static String getMessage(GameId id,
                                String symbolicMessageName)
                         throws NoSuchDataException

Get a message in the language associated with the game id.

Parameters:

id - The id of the game.

symbolicMessageName - The symbolic name of the message.

Returns:

The message in the specified language.

Throws:

NoSuchDataException - Thrown if there is no message for the symbol name.

getLangMessage

private String getLangMessage(String symbolicMessageName)
                       throws NoSuchDataException

Get the specified message.

Parameters:

symbolicMessageName - The symbolic name of the message.

Returns:

The message as a String.

Throws:

NoSuchDataException - Thrown if there is no message for the symbol name.

setMessage

public void setMessage(String symbolicMessageName,
                       String value)
                throws InconsistentStateException

Set a new message for the given symbol. This operation only affects objects in memory. In order for the changes to be saved, the save() method must be called.

Parameters:

symbolicMessageName - The symbolic name of the message.

value - The message in the specified language.

Throws:

InconsistentStateException - Thrown if the symbol does not exist in the default language. This is done to ensure that there is consistency across languages.

removeMessage

public void removeMessage(String symbolicMessageName)

Remove the given symbol. This operation only affects objects in memory. In order for the changes to be saved, the save() method must be called.

Parameters:

symbolicMessageName - The symbolic name of the message.

save

public void save()
          throws InternalErrorException

Save the results of creating or updating a language. The results are written out to the appropriate file.

Throws:

InternalErrorException - Thrown if the operation fails for any reason.

getSymbolicLanguageName

public static String getSymbolicLanguageName(String dispLangName)
                                      throws NoSuchDataException

Get the symbolic language name for the displayable name.

Parameters:

dispLangName - The displayable language name.

Returns:

A String which is the symbolic language name.

Throws:

NoSuchDataException - Thrown if the language name is unknown.

getDefaultLanguageSymbolicName

public static String getDefaultLanguageSymbolicName()

Get the symbolic name of the default language.

Returns:

A String which is the name.

getDefaultLanguageDisplayableName

public static String getDefaultLanguageDisplayableName()

Get the displayable name of the default language.

Returns:

A String which is the name.

getDefaultMessageObject

protected static Message getDefaultMessageObject()
                                          throws InternalErrorException

Get the Message object for the default language.

Returns:

A Message object which is the default language.

Throws:

InternalErrorException - Thrown if the operation fails for any reason.

getDisplayableLanguageNames

public static String[] getDisplayableLanguageNames()

Displayable names for all supportable languages, in the local language.

getSymbolicLanguageNames

public static String[] getSymbolicLanguageNames()

Symbolic names for all supportable languages, in the local language.

reset

protected void reset()
              throws InternalErrorException

Restore the Message object to the values in the messages file.

Throws:

InternalErrorException - Thrown if the operation fails for any reason.

hashCode

public int hashCode()

Get a hash code for this object.

Overrides:

hashCode in class Object

Returns:

An int which is the hash code.

equals

public boolean equals(Object o)

Test this object for equality with another one.

Overrides:

equals in class Object

Parameters:

o - The object being tested.

Returns:

true if the two objects are equal, or false.