LocalizableTextFormatter class

The LocalizableTextFormatter class, found in the package com.ibm.websphere.i18n.localizabletext, 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.

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

Creation and initialization of class instances

LocalizableTextFormatter supports the following constructors:

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

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 article for more information. For a usage example, see Compose complex strings.

API for formatting text

The formatting methods in LocalizableTextFormatter 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 Java virtual macine. All four methods throw LocalizableException objects.

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, 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 apppropriate 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 the issue of 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; this refers to the name of the formatting application, which is not necessarily the name of the application in which the value is set.

Caching of messages

LocalizableTextFormatter can optionally cache formatted messages so that they do not have to be reformatted when needed again. By default, caching is not enabled, but use LocalizableTextFormatter.setCacheSetting(true) to enable caching. When caching is enabled and the format method is called, the method determines whether the message has already been 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 have been cached, those messages remain in the cache until the cache is cleared by a call to LocalizableTextformatter.clearCache(). You 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 can be ignored unless the LocalizableTextFormatter instance throws an exception. To set fallback values, call the following methods as appropriate:

For a usage example, see Generate localized text.

Processing of application-specific values

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

Your formatter class can extend LocalizableTextFormatter or independently implement some or all of the same localizable-text interfaces. As a minimum, your class must implement java.io.Serializable and at least one of the localizable-text interfaces and its corresponding format method. If your 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.