| Optional APIs Porting Guide |    
|
| Optional APIs Porting Guide |
|
| C H A P T E R 6 |
|
Mobile Internationalization API |
The JSR 238 API consists of three main classes:
The Java Wireless Client software provides two implementations for each of these classes.
To select the implementation for each class, set the corresponding variable in jsr238/src/config/config.gmk. The value for each is either java or platform. By default, all three classes use the java_global implementation.
JSR_238_COLLATION_IMPL = java
JSR_238_FORMAT_IMPL = java
JSR_238_RESOURCES_IMPL = java
Note that the java_global implementation of Formatter depends on the java_global implementation of ResourceManager.
When porting the java_global implementation to a new platform, keep in mind the set of supported locales for each of the main classes. Each class can have different set of locales.
For Formatter, the supported locales are determined by the presence of corresponding resource files, containing formatting strings, symbols, and patterns.
You can add a locale by creating common.res and placing it in the global directory, in a subdirectory named for the locale. In addition, update the metafile _common. You can use a JSR 238 resource file editor, like the one in the Sun Java Wireless Toolkit.
The file common.res has a standard format used by ResourceManager and described in JSR 238. It must contain resources with following types and IDs:
TYPE_NUMBER_FORMAT_SYMBOLS = (byte) 0xfe;
Constants.NUMBER_FORMAT_SYMBOL_RESOURCE_ID=7FFFFFFD
TYPE_DATETIME_FORMAT_SYMBOLS = (byte) 0xfd;
Constants.DATETIME_FORMAT_SYMBOL_RESOURCE_ID=7FFFFFFE
The format of these resources can be seen from the following methods:
write(java.io.OutputStream out) of class
com.sun.j2me.global.NumberFormatSymbols
write(java.io.OutputStream out) of class
com.sun.j2me.global.DateFormatSymbols
The java_global implementation of Formatter supports the following locales:
In the current implementation, the behavior of a language-only locale is identical to the corresponding language-with-country locale.
Usually, it is not a good idea to have language-only locales for Formatter, because it is not clear what values to use as default currencies.
The java_global implementation of StringComparator supports the following locales:
The number of string comparator locales is determined in jsr238/src/config/properties_jsr238.xml.
Tailored rules are applied to the Unicode Collation Algorithm table located in _coltable.bin and containing "hot fixes" of general collation rules applied for some specific locale.
The java_global implementation has some limitations on supported locales. Locales that uses "backward ordering" or "context" in collation rules (French or Russian, for example) probably do not work correctly.
The java_global implementation of ResourceManager supports the same locales as Formatter because it relies on same resource files (common.res) existing for each supported locale.
JSR 238 does not define what resources need to be available as platform DEVICE resources and what IDs they need to have. This means DEVICE resources are useful only for a certain implementation. The current java_global implementation provides the following string resources for each locale:
This list can be expanded by adding a new resource to common.res for each supported locale. Document the IDs you add to make them available for other developers in your organization.
The JavaCall API for Formatter relies on the ability of the underlying platform to format dates and numbers for different locales.
To format dates and numbers, the implementation asks the platform to convert an integer or float number to a text representation without any formatting. Two JavaCall API functions, javacall_mi18n_double_to_ascii() and javacall_mi18n_long_to_ascii() do the work.
If the native platform is libc-compliant, the fuctions ltoa() and ecvt() can be used.
The text representation of the number is then passed to formatting functions to apply locale rules. These functions uses formatting patterns for different format types and local symbols for digits and separators. It is likely that the platform has a direct API to do this, but if not, it must at least have access to local formatting symbols and patterns. The existing win32 JavaCall API implementation can be reused to format a number string according to this information.
You might encounter problems with the TCK on an implementation that works with Arabic or Indic locales. The TCK expects the implemention to use only regular digits 0 through 9 in formatting numbers and data, and also it always expects a dash (-) as the minus sign symbol and a percent sign (%) as the percent sign symbol used. Further, it relies on the minus sign going before a number. While it is not correct for some locales, the TCK will fail if it is done another way. To fulfill these requirements, two build variables (NOT_USE_NATIVE_DIGITS, MINUS_ALWAYS_INFRONT) must be defined (set to 1) when building the JavaCall API to satisfy the TCK but compromise correct behavior.
Converting platform locales to JSR 238 locales might be a little tricky. JSR 238 locales consist of an ISO 639 language code, an optional (but recommended) ISO 3166 country code, and an optional variant. Platform locales can consist of more parts, like language, region, script, currency variant, collation variant, calendar variant, and more. Your implementation must extract locales for pure languages and languages with countries, and provide other locales as variants to them. Here is an example:
Part of the JavaCall layer StringComparator API is a function that asks the platform to compare strings using a specific JSR 238 level. The main problem is to convert platform collation flags to JSR 238 collation levels. These are the main rules:
Before comparing, strings must be put to Normalized Canonical Decomposition Form (NFD). Usually, this is done transparently by collation functions on Unicode-supported platforms.
If string normalization and collation is not supported by platform, you can choose to use the java_global implementation for StringComparator, which is independent from other classes.
The JavaCall layer ResourceManager API is responsible only for accessing some predefined platform (DEVICE) resources. All application resources are handled on the Java platform level.
Platform resources can be strings, images, or sounds existing on the platfrom.
The API includes functions for querying the resource type and length and for reading resource data by small chunks (in case the resource is large, such as a large sound file).
All string resources must be passed in a UTF-8 encoded byte array, so the implementation must support encoding of native strings to UTF-8.
All platform resource IDs can be taken from corresponding platform APIs or assigned explicitly and published for future developers.
| Optional APIs Porting Guide | 05-2007 |
|
Copyright © 2007, Sun Microsystems, Inc. All rights reserved. SUN PROPRIETARY/CONFIDENTIAL.