Package de.uni_trier.wi2.procake.utils.multilanguage

Interface MessageFormatter

  • All Known Implementing Classes:
    MessageFormatterImpl
    public interface MessageFormatter
    The MessageFormatter loads and formats local messages. This should be used to localize the system.

    Message Loading

    All aspects of the message loading is descript in the package description de.uni_trier.wi2.procake.utils.multilanguage. Since version 0.4 it is possible to specify the classloader that should load the resource bundle. If no classloader is specified, the class loader of the message formatter implementation is used. But for agents that are loaded with an own classloader this does not work because the agent resources are placed in the agent jar package. Therefore, the agent can specify the class loader that should be used to load the resources, eg., the classloader of the agent.

    Message Formatting

    This explanation is taken from MessageFormat. MessageFormatter provides a means to produce concatenated messages in language-neutral way. Use this to construct messages displayed for end users.

    MessageFormatter takes a set of objects, formats them, then inserts the formatted strings into the pattern at the appropriate places.

    If the component or key can not be found in the resource bundle, the key is used as pattern.

    Patterns and Their Interpretation

    MessageFormatter uses patterns of the following form: 
    

   <i>MessageFormatPattern:</i>
           <i>String</i>
           <i>MessageFormatPattern</i> <i>FormatElement</i> <i>String</i>

   <i>FormatElement:</i>
           { <i>ArgumentIndex</i> }
           { <i>ArgumentIndex</i> , <i>FormatType</i> }
           { <i>ArgumentIndex</i> , <i>FormatType</i> , <i>FormatStyle</i> }

   <i>FormatType: one of </i>
           number date time

   <i>FormatStyle:</i>
           short
           medium
           long
           full
           integer
           currency
           percent
           <i>SubformatPattern</i>

   <i>String:</i>
           <i>StringPart<sub>opt</sub></i>
           <i>String</i> <i>StringPart</i>

   <i>StringPart:</i>
           ''
           ' <i>QuotedString</i> '
           <i>UnquotedString</i>

   <i>SubformatPattern:</i>
           <i>SubformatPatternPart<sub>opt</sub></i>
           <i>SubformatPattern</i> <i>SubformatPatternPart</i>

   <i>SubFormatPatternPart:</i>
           ' <i>QuotedPattern</i> '
           <i>UnquotedPattern</i>

    Within a String , "''" represents a single quote. A QuotedString can contain arbitrary characters except single quotes; the surrounding single quotes are removed. An UnquotedString can contain arbitrary characters except single quotes and left curly brackets. Thus, a string that should result in the formatted message "'{0}'" can be written as "'''{'0}''" or "'''{0}'''".

    Within a SubformatPattern , different rules apply. A QuotedPattern can contain arbitrary characters except single quotes; but the surrounding single quotes are not removed, so they may be interpreted by the subformat. For example, "{1,number,$'#',##}" will produce a number format with the pound-sign quoted, with a result such as: "$#31,45". An UnquotedPattern can contain arbitrary characters except single quotes, but curly braces within it must be balanced. For example, "ab {0} de" and "ab '}' de" are valid subformat patterns, but "ab {0'}' de" and "ab } de" are not.

    Warning:
    The rules for using quotes within message format patterns unfortunately have shown to be somewhat confusing. In particular, it isn't always obvious to localizers whether single quotes need to be doubled or not. Make sure to inform localizers about the rules, and tell them (for example, by using comments in resource bundle source files) which strings will be processed by MessageFormat. Note that localizers may need to use single quotes in translated strings where the original version doesn't have them.

    The ArgumentIndex value is a non-negative integer written using the digits '0' through '9', and represents an index into the arguments array passed to the format methods or the result array returned by the parse methods. The component and the key are added automatically to the arguments. Consequently, argument index '0' is always the component, '1' is the key, and the given parameters are starting at index '2'.

    The FormatType and FormatStyle values are used to create a Format instance for the format element. The following table shows how the values map to Format instances. Combinations not shown in the table are illegal. A SubformatPattern must be a valid pattern string for the Format subclass used.

    //Shows how FormatType and FormatStyle values map to * Format instances"

    Format Type Format Style Subformat Created
    (none) (none) null
    number (none) NumberFormat.getInstance(getLocale())
    integer NumberFormat.getIntegerInstance(getLocale())
    currency NumberFormat.getCurrencyInstance(getLocale())
    percent NumberFormat.getPercentInstance(getLocale())
    SubformatPattern new DecimalFormat(subformatPattern, new DecimalFormatSymbols(getLocale()))
    date (none) DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())
    short DateFormat.getDateInstance(DateFormat.SHORT, getLocale())
    medium DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())
    long DateFormat.getDateInstance(DateFormat.LONG, getLocale())
    full DateFormat.getDateInstance(DateFormat.FULL, getLocale())
    SubformatPattern new SimpleDateFormat(subformatPattern, getLocale())
    time (none) DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())
    short DateFormat.getTimeInstance(DateFormat.SHORT, getLocale())
    medium DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())
    long DateFormat.getTimeInstance(DateFormat.LONG, getLocale())
    full DateFormat.getTimeInstance(DateFormat.FULL, getLocale())
    SubformatPattern new SimpleDateFormat(subformatPattern, getLocale())
    FormatType and FormatStyle mapping to instances

    Usage Information

    Here are some examples of usage: 

     Object[] arguments = { new Integer(7), new Date(System.currentTimeMillis()),
                "a disturbance in the Force" };

 String result = MessageFormatter.format("component",
       "1232",
       arguments);

 example /resources/Messages/component.properties entry:
   1232=At {3,time} on {3,date}, there was {4} on planet {2,number,integer} ({0}:{1}).

 
 output:
 

 At 12:30 PM on Jul 3, 2053, there was a disturbance
             in the Force on planet 7 (component:1232).

    Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.

    Author:
    Rainer Maximini
    See Also:
    Locale, Format, NumberFormat, DecimalFormat, ChoiceFormat