+

Search Tips   |   Advanced Search

LocalizableTextFormatter class

The LocalizableTextFormatter class, found in the com.ibm.websphere.i18n.localizabletext package, is the primary programming interface for using the localizable-text package. Instances of this class contain the information needed to create language-specific strings from keys and resource bundles.

The LocalizableTextFormatter class extends the java.lang.Object class and implements the following interfaces:


Creation and initialization of class instances

The LocalizableTextFormatter class supports the following constructors:

The LocalizableTextFormatter instance must have certain values, such as a resource-bundle name, a key, and the name of the formatting application. If we do not pass these values in using the second constructor listed previously, we can set them separately by making the following calls:

We can use a fourth method, setArguments(Object[] args), to set optional localization values after construction. See Processing of application-specific values at the end of this topic. For a usage example, see Composing complex strings.


API for formatting text

The formatting methods in the LocalizableTextFormatter class generate a string from a set of message keys and resource bundles, based on some combination of locale and time-zone values. Each method corresponds to one of the four localizable-text interfaces implemented. The following list indicates the interface in which each formatting method is defined:

The format method with no arguments uses the locale and time-zone values set as defaults for the JVM. All four methods issue LocalizableException objects as needed.


Location of message catalogs and the appName value

Applications written with the localizable-text package can access message catalogs locally or remotely. In a distributed environment, the use of remote, centrally located message catalogs is appropriate. All clients can use the same catalogs, and maintenance of the catalogs is simplified. Local formatting is useful in test situations and appropriate under some circumstances. To support either local or remote formatting, a LocalizableTextFormatter instance must indicate the name of the formatting application.

For example, when an application formats a message by using remote catalogs, the message is actually formatted by an enterprise bean on the server. Although the localizable-text package contains the code to automate the lookup of the formatter bean and to issue a call to it, the application needs to know the name of the formatter bean. Several methods in the LocalizableTextFormatter class use a value described as appName, which refers to the name of the formatting application. It is not necessarily the name of the application in which the value is set.


Caching of messages

LocalizableTextFormatter instances can optionally cache formatted messages so that they do not require reformatting when needed again. By default, caching is not enabled, but we can use a LocalizableTextFormatter.setCacheSetting(true) call to enable caching. When caching is enabled and the format method is called, the method determines whether the message is already formatted. If so, the cached message is returned. If the message is not found in the cache, the message is formatted and returned to the caller, and a copy of the message is cached for future use.

If caching is disabled after messages are cached, those messages remain in the cache until the cache is cleared by a call to the LocalizableTextformatter.clearCache method. We can clear the cache at any time; the cache is automatically cleared when any of the following methods is called:


API for providing fallback information

Under some circumstances, it can be impossible to format a message. The localizable-text package implements a fallback strategy, making it possible to get some information even if a message cannot be formatted correctly into the requested language. The LocalizableTextFormatter instance can optionally store fallback values for a message string, the time zone, and the locale. These values can be ignored unless the LocalizableTextFormatter instance issues an exception. To set fallback values, call the following methods as appropriate:

For a usage example, see Generating localized text.


Processing of application-specific values

The localizable-text package provides native support for localization based on time zone and locale, but we can construct messages on the basis of other values as well. If we need to consider variables other than locale and time zone in formatting localized text, write our own formatter class.

Your formatter class can extend the LocalizableTextFormatter class or independently implement some or all of the same localizable-text interfaces. As a minimum, the class must implement the java.io.Serializable interface and at least one of the localizable-text interfaces and its corresponding format method. If the class implements more than one localizable-text interface and format method, the order of evaluation of the interfaces is as follows:

  1. LocalizableTextLTZ

  2. LocalizableTextL

  3. LocalizableTextTZ

  4. LocalizableText

As an example, the localizable-text package provides a class that reports the time and date (LocalizableTextDateTimeArgument). In that class, date and time formatting is localized in accordance with three values: locale, time zone, and style.


Related tasks

  • Task overview: Internationalizing interface strings (localizable-text API)
  • Composing complex strings
  • Generating localized text
  • Customize the behavior of a formatting method

  • Globalization: Resources for learning
  • Localization API support