com.ibm.websphere.i18n.localizabletext
Class LocalizableTextFormatter

java.lang.Object
  |
  +--com.ibm.websphere.i18n.localizabletext.LocalizableTextFormatter
All Implemented Interfaces:
Localizable, LocalizableText, LocalizableTextL, LocalizableTextLTZ, LocalizableTextTZ, java.io.Serializable

public class LocalizableTextFormatter
extends java.lang.Object
implements LocalizableText, LocalizableTextL, LocalizableTextTZ, LocalizableTextLTZ, java.io.Serializable

The LocalizableTextFormatter object is the main class used in the Localizable service.

The Localizable Text function is the infrastructure to enable the retrieval of translated text to any desired locale/time zone in a distributed environment. With the use of a LocalizableTextFormatter object, the user can set the needed information in a language neutral way. When the information is needed to be displayed to a user, the LocalizableTextFormatter object can be formatted into the locale/time zone of the user. Typical uses will be to hold error and exception information, inform users of invalid parameters in a request, log data, GUI screen information or just about anything a user may want to have displayed. Text strings, numbers, currency, dates, times, and time zones are all specific to the user's language/country and need to be processed correctly.

Arguments
In any LocalizableTextFormatter, arguments are optional. The dependency for arguments falls completely on the pattern key. In addition to the normal arguments that are used with pattern keys, the Localizable Text function adds a few extra options. The four interfaces, LocalizableText, LocalizableTextL, LocalizableTextTZ and LocalizableTextLTZ allow additional objects to be used as arguments. The object LocalizableTextDateTimeArgument is an example class of what can be done when using one of the four interfaces. Any one or more of the interfaces can be implemented by another class. When multiple interfaces are implemented, there is a specific order in which the class will be evaluated so that the proper format method is called.
The order of evaluation is:

  1. LocalizableTextLTZ
  2. LocalizableTextL
  3. LocalizableTextTZ
  4. LocalizableText
See any of those four interfaces for further detail on how to use them.

Another argument that can be used, is a second LocalizableTextFormatter, which implements all four of the Localizable interfaces. This allows the user of LocalizableTextFormatters to nest multiple LocalizableTextFormatters within another. Where this would be useful is if you have a base message in one resource bundle, and some additional information in a second resource bundle. That way, with the use of two resource bundles, the single message can be combined at formatting time.

Note:    The classes for the objects used as arguments must be on the system where the LocalizableTextFormatter is created and also on the system where the formatting "actually" takes place. The argument classes do not need to be on any other systems in the network. This is accomplished by internally copying the contents of the argument objects, rather than using references to them. In a typical remote formatting example, a LocalizableTextFormatter object and it's associated arguments are created by an application on a server, then passed over the wire to a client. When the client calls the format method on the LocalizableTextFormatter, the actual formatting is not done on the client machine, but on a server where the target Resource Bundles reside. Therefore, all classes for the argument objects in the array must exist on that remote server and do not need to exist on the client. Even though Java uses references for objects, Localizable Text internally uses copies of the objects. Another example use would be when a LocalizableTextFormatter (LTF1) contains an argument array with a reference to another LocalizableTextFormatter (LTF2). If the contents of LTF2 is changed, the changes will NOT automatically be reflected in LTF1. In order for LTF1 to reflect the changes in LTF2, the argument array in LTF1 must be set again with the changed LTF2.

An example would be:
...
...
catch (Exception exp) {
   String className = this.getClass().getName();
   LocalizableTextFormatter messageLTF = new LocalizableTextFormatter("Error_125", "resources.Messages");
   Object[] args = {className, messageLTF};
   LocalizableTextFormatter exceptionLTF = new LocalizableTextFormatter("General_Error", "resources.Exceptions", args);
}
...
...
...
// Exception was caused by a problem with foo,
// change pattern key in messageLTF to reflect this
messageLTF.setPatternKey("Error_235");

//Display exception to user
System.out.println(exceptionLTF.format(myLocale));
...
...

When the format was called on the exceptionLTF, it resulted in displaying the wrong information to the user. What the programmer should have done is:

...
...
// Exception was caused by a problem with foo,
// change pattern key in messageLTF to reflect this
messageLTF.setPatternKey("Error_235");
exceptionLTF.setArguments(className, messageLTF);

//Display exception to user
System.out.println(exceptionLTF.format(myLocale));
...
...


Cache
The LocalizableTextFormatter object has the ability to cache formatted messages. By default, the caching ability is turned off, or set to false. When the cache setting is set to true, the behavior of the LocalizableTextFormatter changes. First, when the format method is called, the method checks to see if the LocalizableTextFormatter has already been formatted. The cache is checked with the combination of the Locale passed and the TimeZone passed. If no Locale and/or TimeZone object(s) are passed, the JVM default values are used. If the LocalizableTextFormatter has already been formatted, then the previously formatted String is returned. If the Locale/TimeZone combination is not found, then the LocalizableTextFormatter is formatted as normal. The returned String is cached for future use as well as returned to the caller of the format method. If the cacheSetting is set to false, and the cache already contains formatted Strings, those Strings will remain in the cache until the LTF.clearCache() is invoked. If any one of the following four methods are called, the cache will be cleared. The caches is cleared so that the contents of the cache and the result from formatting the LocalizableTextFormatter stays consistent with each other.

FallBack Text
When formatting is not possible because or various reasons, it may be necessary to know the contents of a message without being about to display the information in the clients language. With that in mind, a Fallback strategy has been implemented. The user can optionally have a translated string saved as Fallback text. If the LocalizableTextFormatter throws an exception, the Fallback text, Fallback locale and Fallback time zone can be retrieved for use for error recovery / avoidance.

An example would be:

...
...
public void displayText(LocalizableTextFormatter ltf, Locale desiredLocale) {

try {
   System.out.println(ltf.format(desiredLocale));
}
catch (LocalizableException le) {
   System.out.println(ltf.getFallBackText());
}

return;

}
...
...


See Also:
LocalizableText, LocalizableTextL, LocalizableTextTZ, LocalizableTextLTZ, LocalizableTextDateTimeArgument, Serialized Form

Constructor Summary
LocalizableTextFormatter()
          Default constructor.
LocalizableTextFormatter(java.lang.String resourceBundleName, java.lang.String patternKey, java.lang.Object[] arguments, java.lang.String applicationName)
          Constructs a LocalizableTextFormatter object with the package qualified ResourceBundle name, the String of the pattern key in the ResourceBundle, the Object[] of arguments and the name of the server application.
LocalizableTextFormatter(java.lang.String resourceBundleName, java.lang.String patternKey, java.lang.String applicationName)
          Constructors a LocalizableTextFormatter object with the package qualified ResourceBundle name and the String of the pattern key to use from the ResourceBundle.
 
Method Summary
 void clearCache()
          Clears the contents of the LocalizableTextFormatters cache.
 void clearLocalizableTextFormatter()
          Resets the state of the LocalizableTextFormatter object back to a new instance state.
 boolean equals(java.lang.Object obj)
          Determines whether the object passed in is "equal to" this LocalizableTextFormatter.
 java.lang.String format()
          Formats this object with the set pattern key from the specified Resource Bundle and any optional arguments to produce a String.
 java.lang.String format(java.util.Locale loc)
          Formats this object with the pattern key from the specified Resource Bundle and any optional arguments to produce a String.
 java.lang.String format(java.util.Locale localeIn, java.util.TimeZone timeZoneIn)
          Formats this object with the pattern key from the specified Resource Bundle and any optional arguments to produce a String.
 java.lang.String format(java.util.TimeZone timeZone)
          Formats this object with the pattern key from the specified Resource Bundle and any optional arguments to produce a String.
 java.lang.String getApplicationName()
          Returns the application name associated with this LocalizableTextFormatter.
 java.lang.Object[] getArguments()
          Returns an array of objects that were set for use with this LocalizableTextFormatter.
 java.lang.String getCacheEntry(java.util.Locale locale, java.util.TimeZone timeZone)
          Returns a previously formatted String from the cache based on the Locale and TimeZone passed.
 boolean getCacheSetting()
          Used to get the setting for cacheing.
 java.util.Locale getFallBackLocale()
          Used to get the FallBackLocale.
 java.lang.String getFallBackString()
          Used to get the FallBack String.
 java.util.TimeZone getFallBackTimeZone()
          Used to get the FallBackTimeZone.
 java.lang.String getPatternKey()
          Returns the pattern key for this LocalizableTextFormatter.
 java.lang.String getResourceBundleName()
          Returns the name of the ResourceBundle to use for this LocalizableTextFormatter.
 int hashCode()
          Generates a HashCode for this LocalizableTextFormatter object.
 java.lang.String localFormat(java.util.Locale localeIn, java.util.TimeZone timeZoneIn)
          Formats the LocalizableTextFormatter object locally.
 void setApplicationName(java.lang.String appName)
          Set the application name for the LocalizableTextFormatter object.
 void setArguments(java.lang.Object[] args)
          Sets the arguments for the LocalizableTextFormatter to use with the set pattern key.
 void setCacheSetting(boolean setting)
          Sets the cache behavior of this LocalizableTextFormatter object.
 void setFallBackLocale(java.util.Locale newFallBackLocale)
          Sets a Locale object to use with this LocalizableTextFormatter object.
 void setFallBackString(java.lang.String newFallBackString)
          Sets a String object to use with this LocalizableTextFormatter object.
 void setFallBackTimeZone(java.util.TimeZone newFallBackTimeZone)
          Sets a TimeZone object to use with this LocalizableTextFormatter object.
 void setPatternKey(java.lang.String patternKey)
          Sets the pattern key to use.
 void setResourceBundleName(java.lang.String bundleName)
          Sets the ResourceBundle name to use for this message.
 java.lang.String toString()
          Displays all of the current information in the object.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LocalizableTextFormatter

public LocalizableTextFormatter()
Default constructor.

LocalizableTextFormatter

public LocalizableTextFormatter(java.lang.String resourceBundleName,
                                java.lang.String patternKey,
                                java.lang.Object[] arguments,
                                java.lang.String applicationName)
Constructs a LocalizableTextFormatter object with the package qualified ResourceBundle name, the String of the pattern key in the ResourceBundle, the Object[] of arguments and the name of the server application.
Parameters:
resourceBundleName - The name of the fully package qualified ResourceBundle to be used.
patternKey - The key to be used to get the pattern from the ResourceBundle.
arguements - An array of objects to be used as arguments for the pattern (in any).
applicationName - The name of the application running on the application server(s) where the ResourceBundle can be found.

LocalizableTextFormatter

public LocalizableTextFormatter(java.lang.String resourceBundleName,
                                java.lang.String patternKey,
                                java.lang.String applicationName)
Constructors a LocalizableTextFormatter object with the package qualified ResourceBundle name and the String of the pattern key to use from the ResourceBundle.
Parameters:
resourceBundleName - The name of the fully package qualified ResourceBundle to be used.
patternKey - The key to be used to get the pattern from the ResourceBundle.
Method Detail

clearLocalizableTextFormatter

public void clearLocalizableTextFormatter()
Resets the state of the LocalizableTextFormatter object back to a new instance state. The purpose of this method is so that LocalizableTextFormatter objects can be re-used.

equals

public boolean equals(java.lang.Object obj)
Determines whether the object passed in is "equal to" this LocalizableTextFormatter. Everything in the two objects are checked for equality on an element per element basis.
Overrides:
equals in class java.lang.Object
Parameters:
obj - the object with which to compare this one to.
Returns:
boolean

format

public java.lang.String format()
                        throws LocalizableException
Formats this object with the set pattern key from the specified Resource Bundle and any optional arguments to produce a String. The String returned is in the language specified by the default Locale of the callers JVM.
Specified by:
format in interface LocalizableText
Returns:
java.lang.String - The language specific message.

format

public java.lang.String format(java.util.Locale loc)
                        throws LocalizableException
Formats this object with the pattern key from the specified Resource Bundle and any optional arguments to produce a String. The String returned is in the language specified by the passed Locale.
Specified by:
format in interface LocalizableTextL
Parameters:
loc - The Locale to format the LocalizableTextFormatter into.
Returns:
java.lang.String - The language specific message.

format

public java.lang.String format(java.util.Locale localeIn,
                               java.util.TimeZone timeZoneIn)
                        throws LocalizableException
Formats this object with the pattern key from the specified Resource Bundle and any optional arguments to produce a String. The String returned is in the language specified by the passed Locale. The TimeZone passed can be used by any arguments for date / time sensitive processing.
Specified by:
format in interface LocalizableTextLTZ
Parameters:
localeIn - A Locale representing the language to format this LocalizableTextFormatter into.
timeZoneIn - A TimeZone for any date / time sensitative arguments.
Returns:
String
See Also:
LocalizableTextDateTimeArgument

format

public java.lang.String format(java.util.TimeZone timeZone)
                        throws LocalizableException
Formats this object with the pattern key from the specified Resource Bundle and any optional arguments to produce a String. The String returned is in the language specified by the callers default JVM Locale. The TimeZone passed can be used by any arguments for date / time sensitive processing.
Specified by:
format in interface LocalizableTextTZ
Returns:
java.lang.String
See Also:
format(Locale, TimeZone)

getArguments

public java.lang.Object[] getArguments()
                                throws LocalizableException
Returns an array of objects that were set for use with this LocalizableTextFormatter.
Returns:
Object[]

getCacheSetting

public boolean getCacheSetting()
Used to get the setting for cacheing. The default setting is false.
Returns:
boolean

getFallBackLocale

public java.util.Locale getFallBackLocale()
Used to get the FallBackLocale. The FallBackLocale is a holder for a java.util.Locale object. It can be used when an error occurs during formatting of the LocalizableTextFormatter object. If an error occurs, the user of the LocalizableTextFormatter object has to call this method to get the Locale object.
Returns:
java.util.Locale

getFallBackString

public java.lang.String getFallBackString()
Used to get the FallBack String. The FallBackString is a holder for java.lang.String object. It can be used when an error occurs during formatting of the LocalizableTextFormatter object. If an error occurs, the user of the LocalizableTextFormatter object has to call this method to get the String object. The String that is returned will not necessarily be in the language desired by the caller using this LocalizableTextFormatter object. It will be in whatever language that was set. If the locale is to be known, use the LocalizableTextFormatter.setFallBackLocale / LocalizableTextFormatter.getFallBackLocale methods.
Returns:
java.lang.String

getFallBackTimeZone

public java.util.TimeZone getFallBackTimeZone()
Used to get the FallBackTimeZone. The FallBackTimeZone is a holder for java.util.TimeZone object. It can be used when an error occurs during formatting of the LocalizableTextFormatter object. If an error occurs, the user of the LocalizableTextFormatter object has to call this method to get the TimeZone object.
Returns:
java.util.TimeZone

getPatternKey

public java.lang.String getPatternKey()
Returns the pattern key for this LocalizableTextFormatter. Returns null if a key has not been previously set.
Returns:
java.lang.String

getResourceBundleName

public java.lang.String getResourceBundleName()
Returns the name of the ResourceBundle to use for this LocalizableTextFormatter. Returns null if a name has not been previously set.
Returns:
java.lang.String

hashCode

public int hashCode()
Generates a HashCode for this LocalizableTextFormatter object. The hash code follows the give set of rules for hash codes as outlined in the java specification.
Overrides:
hashCode in class java.lang.Object
Returns:
int

localFormat

public java.lang.String localFormat(java.util.Locale localeIn,
                                    java.util.TimeZone timeZoneIn)
                             throws LocalizableException
Formats the LocalizableTextFormatter object locally. When this method is used, the ResourceBundle must exist in the local classpath. This method can also be used independantly of the LocalizableTextResourceAccessor EJB.
Parameters:
locale - java.util.Locale
timeZone - java.util.TimeZone
Returns:
java.lang.String

setArguments

public void setArguments(java.lang.Object[] args)
Sets the arguments for the LocalizableTextFormatter to use with the set pattern key. An object[] is optional when formatting a LTF. All objects passed in are copied before storing. Objects passed in the object[] must either implement the Serializable, or one of the LocalizableText interfaces. If the object is an EJB, the handle is stored and not the EJB itself. Other LocalizableTextFormatter objects can be passed in the object[] as well.
If caching is being used, calling this method will clear the cache also. See javadoc header for more details.
Returns:
java.lang.Object[]
See Also:
LocalizableText, LocalizableTextL, LocalizableTextTZ, LocalizableTextLTZ

setCacheSetting

public void setCacheSetting(boolean setting)
Sets the cache behavior of this LocalizableTextFormatter object. The default setting is false, or the cache is turned off.
Parameters:
setting - boolean

setFallBackLocale

public void setFallBackLocale(java.util.Locale newFallBackLocale)
Sets a Locale object to use with this LocalizableTextFormatter object. See the LocalizableTextFormatter object description for more detail.
Parameters:
newFallBackLocale - java.util.Locale
See Also:
LocalizableTextFormatter

setFallBackString

public void setFallBackString(java.lang.String newFallBackString)
Sets a String object to use with this LocalizableTextFormatter object. See the LocalizableTextFormatter object description for more detail.
Parameters:
newFallBackString - java.lang.String
See Also:
LocalizableTextFormatter

setFallBackTimeZone

public void setFallBackTimeZone(java.util.TimeZone newFallBackTimeZone)
Sets a TimeZone object to use with this LocalizableTextFormatter object. See the LocalizableTextFormatter object description for more detail.
Parameters:
newFallBackTimeZone - java.util.TimeZone
See Also:
LocalizableTextFormatter

setPatternKey

public void setPatternKey(java.lang.String patternKey)
Sets the pattern key to use. A pattern key is required before formatting the LocalizableTextFormatter. If the pattern key is not set before formatting, a NullPointerException is thrown from the format method. The pattern key is from the ResourceBundle that is set to be used with this LocalizableTextFormatter.
If caching is being used, calling this method will clear the cache also. See javadoc header for more details.
Parameters:
java.lang.String -  

setResourceBundleName

public void setResourceBundleName(java.lang.String bundleName)
Sets the ResourceBundle name to use for this message. A ResourceBundle name is required before formatting the LocalizableTextFormatter. If the ResourceBundle name is not set before formatting, a NullPointerException is thrown from the format method.
If caching is being used, calling this method will clear the cache also. See javadoc header for more details.
Parameters:
java.lang.String -  

toString

public java.lang.String toString()
Displays all of the current information in the object. It does not display the information in the cache. If other LocalizableTextFormatter objects are stored in the argument[], they are fully displayed as well.
Overrides:
toString in class java.lang.Object

clearCache

public void clearCache()
Clears the contents of the LocalizableTextFormatters cache. This methods works if cacheing is set to either true or false.

getCacheEntry

public java.lang.String getCacheEntry(java.util.Locale locale,
                                      java.util.TimeZone timeZone)
Returns a previously formatted String from the cache based on the Locale and TimeZone passed. A null is returned if the cache entry is not found.
Parameters:
locale - Locale to use when looking for a cache entry.
timeZone - TimeZone to use when looking for a cache entry.
Returns:
String

getApplicationName

public java.lang.String getApplicationName()
Returns the application name associated with this LocalizableTextFormatter.
Returns:
java.lang.String

setApplicationName

public void setApplicationName(java.lang.String appName)
Set the application name for the LocalizableTextFormatter object. The application name is used to associate the LTF object with the location of where the ResourceBundles have been deployed.
If caching is being used, calling this method will clear the cache also. See javadoc header for more details.
Parameters:
applicationName - java.lang.String