Imagine that you write an extension to OGSA-DAI (e.g. a new activity or data resource) that logs a message when it has been initialised. If you log a plain message saying "Hello World!" this will only be understood if the user knows English.

OGSA-DAI provides a mechanism for you to register your own messages (a so-called message bundle with OGSA-DAI. This is very useful if you wish to enable internationalization for your extensions to OGSA-DAI (e.g. your activities or data resources) without editing the OGSA-DAI's own message bundle or source code.

In fact, in order to integrate with the OGSA-DAI logging components and log messages using our uk.org.ogsadai.common.msgs.DAILogger class you must adopt this approach.

You can create your own message bundle as a simple Java properties file. This is a list of what are termed message keys which map to strings in whatever language you want. For example, a file my_messages.properties may contain the following messages:

com.example.HELLO_WORLD_MESSAGE=Hello World!
com.example.MISSING_INPUT_ERROR=Missing user input
com.example.PARAMETER_VALUE_OUT_OF_BOUNDS_ERROR=Value {0} exceeds permitted range of this parameter

	Note
	Note that the file extension must be .properties or it will not be picked up by Java.

Each string which a message key maps to may contain placeholders for arguments. Arguments for these placeholders are provided in-code whenever messages are logged (or, for messages associated with errors, whenever exceptions are logged). The placeholders in a single string must range in order from {0} to {N}. The third entry of the example above contains an example of a message with placeholders.

Your message bundles, such as my_messages.properties, can be placed in the CLASSPATH of your OGSA-DAI server.

Alternatively your message bundle may be included within a JAR and added to the OGSA-DAI server like any other JAR.

In your code you can now register your message bundle with the OGSA-DAI message loader (uk.org.ogsadai.common.msgs.MessageLoader). For example:

MessageLoader.registerMessageBundle("my_messages", 
                                    java.util.Locale.getDefault());

The first argument is the base name of the message bundle. If the message bundle is within a package in a JAR then this must be the package-qualified name. The second argument specifies the locale for which the message bundle is desired. This can be the default locale, as in the example above, or any other locale you wish to use. The message loader then tries to load the appropriate resource bundle from the CLASSPATH

Java resource bundles belong to families whose members share a common base name, but whose names also have additional components that identify their locales. For example, if there is a German message bundle provided for the family with base name my_messages the file would be named my_messages_de.properties. Whenever the German locale is requested messages from this bundle will be loaded.

Please see Sun's Java documentation for a complete description of resource bundles.

You now have your messages loaded into OGSA-DAI and indexed by their message keys. These are now available for you to use. So how do you use them? Firstly, you need to declare a message ID. A message ID is an in-code representation of a message key as it appears in a message bundle. These are represented in your code by uk.org.ogsadai.common.msgs.MessageID objects.

For example, you create an identifier for a message key as follows:

public static final MessageID HELLO_WORLD_MSG = 
    new MessageID("com.example.HELLO_WORLD_MESSAGE");

You can then use the OGSA-DAI uk.org.ogsadai.common.msgs.DAILogger to log this message. Your code for logging the information message might look like this:

DAILogger log = DAILogger.getLogger(MyClass.class);
log.info(HELLO_WORLD_MSG);

The value of the HELLO_WORLD_MSG message ID is the message key that is used to search the current message bundle. If a matching entry is found then the value of that entry is logged. If no entry is found then the value of the key (e.g. com.example.HELLO_WORLD_MSG) is logged - for this reason, it is recommended that the message ID itself have a meaningful name.

The message bundle to use is chosen according to Java's standard selection of resource bundles based upon the notion of locales. See the Java documentation for a complete description of Java resource bundles and localization.

A special sub-class of message IDs called error IDs (uk.org.ogsadai.exception.ErrorID) can be used for internationalizing messages associated with OGSA-DAI exceptions. These hold what are termed error keys (as opposed to message keys) but their purpose is the same - to provide an index into a message bundle.

If you derive your exceptions from OGSA-DAI exceptions then you can use error IDs and error keys to support internationalization of your messages using message bundles - the tutorial on Chapter 37, How to write OGSA-DAI compliant exceptions describes this in more detail.