Defining Message Text

Overview

In MetaBoss programming model an operation may return zero or more various Message objects to indicate certain outcomes. Working with Message objects is similar to working with Java Exceptions. Every type of message is represented by distinct Java class, which implements com.metaboss.enterprise.messages.Message interface. In addition each Message object can carry a number of data fields, which are accessible via dedicated getter methods. This approach simplifies and formalises automatic operation outcome analysis. In other words it is not necessary to parse the text of the message in order to understand what has happened.

Despite not playing a major role in automatic processes, the text of the message is very important for humans. Humans normally would want to read message in natural language. This is why every message object has two methods toString() and toLocalisedString(). These methods are 'rendering' message object in the default locale or in the specified locale.

Text Resource Files

Actual text of the messages is defined in resource property files. This technique is defined in java.util.ResourceBundle and java.util.PropertyResourceBundle classes. The text obtained from these property files is ultimately processed by java.text.MessageFormat class. Please refer to JDK documentation for these classes for more information on the text resources and internationalisation. In brief:

• MetaBoss generator places Message.properties file in every servicemodule java package.
• This file contains default version of message text keyed on the unique model reference of the particular message. The default text placed in this file comes from the model (see more detailed discussion below). Text from this file will be used in cases when specific text for the locale is not found.
• Localised versions of this file have to be prepared manually (MetaBoss does not support modelling of localised messages yet). In order for the localised file to be picked up it has to be named as discussed in JDK (basically suffixed with language and locality codes) and placed in the appropriate servicemodule java package. We suggest to create and put on the classpath a special internationalisation jar. This jar may contain all localised message files (ensure that the files are in appropriate subdirectories).

Specifying Default Message Text

As it has been mentioned earlier, the default text for every message comes from the model. Each Message model element has a Default Message attribute. This attribute contains a default message text. Simple macro language is supported here to allow symbolic references to message fields. At code generation time Message Fields references are substituted by actual argument positions as required java.text.MessageFormat class. At run time, when toString() or toLocalisedString() is called, Message object fetches the text string from the appropriate resource bundle, lines up all message fields in certain order and calls java.text.MessageFormat utility class to do merge. The string result of this merge is returned from the toString() or toLocalisedString() for diplaying, printing etc.

Message text definition macro language syntax is in Apache Ant / Velocity style with only one supported reserved word:

• ${Fields.<message field name>} - the occurrence of this expression will be substituted with the expression required by java.text.MessageFormat (essentially position of this field in the lineup of message fields during rendering)

Some examples

• You have mail !

  In this example text does not have any macros, so it will appear in the default message properties file as is.

• File "${Fields.FileName}" not found.

  In this example the '${Fields.FileName}' macro will be substituted with the '{0}', which tells java.text.MessageFormat to replace it with the string supplied in the very first argument durng merge process.