How to Register New Message Bundles

Imagine that you write an extension to OGSA-DAI (e.g. a new activity or data resource accessor) 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 with the OGSA-DAI Message Loader. This is very useful if you wish to enable internationalization for your extensions to OGSA-DAI (e.g. your activities or data resource accessors) 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.

How to create and register your own message bundle

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 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 container:

For OGSA-DAI WSI on Tomcat this is typically: $CATALINA_HOME/webapps/axis/WEB-INF/classes
For OGSA-DAI WSRF on Tomcat this is typically: $CATALINA_HOME/webapps/wsrf/WEB-INF/classes
For OGSA-DAI WSRF in the Globus Toolkit container this is typically: $GLOBUS_LOCATION

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

How to register your message bundle with OGSA-DAI

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.

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

How to define message IDs

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_MESSAGE) 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 ResourceBundles and localization.

The tutorial on How to Use OGSA-DAI Logging describes logging using DAILogger in detail.

Error IDs and error keys

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 How to Define OGSA-DAI-compliant Exceptions describes this in more detail.