International date/time and currency processing depends on ICU4J library version
Summary
Different versions of the ICU4J library (International Component for UNICODE for Java) are used in different versions of Process Commander. As a result, depending upon the version you have, different date/time and currency behavior can occurs. These differences can be difficult to detect and to remedy after an upgrade.
Version 5.3 incorporates a different approach, with benefits described in this article. Version 5.3 does not include any ICU4J library, but instead emulates the functions provided by the ICU4J library in previous version in a way that requires — in all but rare cases — no change to existing code. The Upgrade Readiness tool can help you identify any such rare cases before you upgrade to V5.3.
Quick Links
- ICU Versions in Process Commander
- References to non-public APIs
- Daylight Savings Time changes for Version 4
- Process Commander Version 5.3 – Now Using Java Classes
- Issue: Interpretation of the Y format for dates
- Issue: Decimal Precision in Currency
Suggested Approach
ICU Versions In Process Commander
ICU (International Components for Unicode) is a mature, widely used set of C/C++ and Java libraries for Unicode support, software internationalization and globalization (i18n/g11n). This jar file is available from a SourceForge project started by IBM, and grew out of the JDK 1.1 internationalization APIs, which the ICU team contributed, and the project continues to be developed for the most advanced Unicode/i18n support. ICU is widely portable and gives applications the same results on all platforms and between C/C++ and Java software.
Process Commander uses ICU software in some versions to provide a facility for parsing dates, times, currency qualifiers, and date formatting. This software may also be used to provide internationalization support.
This table identifies the ICU4J versions included in Process Commander versions:
Process Commander Version | ICU4J.jar File Version |
|---|---|
Version 4.1 |
2.6.1 |
Version 4.2 |
2.8 |
Version 5.1 |
3.4.4 |
Version 5.2 |
3.4.4 |
Version 5.3 | no longer used |
References to non-public APIs
Many of the APIs in the ICU4J package are public; however, some are private, which means that the ICU project team can and does change them between versions.
If any applications reference these non-public APIs, the functionality may change from version to version; the application may have to be rewritten to handle the ICU4J functionality in a new version. For example, some Pegasystems Frameworks projects have encountered unexpected differences between ICU 2.8 and ICU 3.4.4.
Version 5.1 includes Public API enhancements 5.1 to eliminate the dependencies from the Frameworks rules and centralize the dependencies in core Process Commander code.
Daylight Savings Time Changes for Version 4
As shown in the table above, Version 4.1 contains ICU4J version 2.6.1. This ICU version is quite out-of-date, and is archived on the ICU web site. Therefore, this version was not updated for recent Daylight Savings Time changes, even though it has time zone rules embedded in its code.
Version 4.2 sites are strongly advised to obtain the icu4j_2_6_1-DST.jar from Global Customer Support. This updated .jar file correctly handles the 2007 Daylight Savings Time changes. Pegasystems has back-ported the ICU 2.8 Time Zone implementation into the 2.6.1 code base, so that time zone rules are based on the rules supplied by the Java Virtual Machine.
Process Commander Version 5.3 - Emulates ICU using Java Classes
ICU4J version 3.4.4 incorporates the Olson 2006a time zone rules (which support the 2007 US Daylight Savings Time changes). Because of volatility of locale and time zone data incorporated into the 3.x series of ICU releases, introduction of newer ICU releases to Process Commander could result in undesirable behavior changes for existing applications.
Therefore, beginning in V5.3, the International Component for Unicode (ICU) classes are replaced with the equivalent classes from the standard Java distribution. This approach has two benefits:
- It makes support for future changes to Daylight Savings Time easier to implement, as developers may now use the time zone data update tools provided by their preferred Java vendor.
- It allows Process Commander to exploit new decimal hardware-assist facilities planned in IBM's Power 6 architecture.
To preserve backwards compatibility with your existing rules that may include references to ICU class names, V5.3 includes a set of thin "wrapper" classes that mimic the commonly used ICU classes to implement this change. As a result, no changes to existing rules or code should be needed.
The date, time and number formats used by ICU are based on data in the Common Locale Data Repository (CLDR), and each release of ICU included updated data formats from the then-current CLDR release. Such variability in the format data could result in visible behavior changes to applications that rely on the default formats for a given locale (as Process Commander typically does), leading to increased training costs for users or unsatisfactory application results
(Because CLDR and ICU organizations do not provide a list of differences between releases, determining what changes have been made requires time-consuming comparison of hundreds of XML files.)
Pegasystems believes that Process Commander users are best served with a consistent stable set of format patterns which applications can then customize, if necessary, for specific requirements. V5.3 incorporates the same formats that are used in V5.1 and V5.2 (based on CLDR 1.3 and ICU 3.4), so the use of emulation wrappers rather than the ICU4J library should be transparent in the most commonly used locales for applications that used only standard formatting characters. (The next release of CLDR data (1.4) —used in ICU 3.5 —introduces significant changes to certain date formats, and was judged to be too disruptive to incorporate into V5.3.)
This emulation package includes those ICU classes and methods that are used within Process Commander. Since developers can to code Java steps (or hand-crafted Java code in other rule types) that reference the ICU4J classes directly, applications may have used other ICU4J classes and methods (beyond those that are emulated). Such rules cannot be compiled in V5.3, as they depend on Java classes that are not present.
To assist in upgrading to V5.3, the Upgrade Readiness tool is enhanced in to scan for references to ICU classes, and report on such usage. This tool scans Java code and flags as issues the use of ICU classes that are not supported, or only partially supported, by the emulation package.
See 
Upgrade Readiness for full details on this tool.
Issue: Interpretation of the Y format for dates
One V5.3 ICU issue is not flagged by the Upgrade Readiness tool/
Some developers had inadvertently used the year format character 'Y' (uppercase y) where they intended to use 'y' (lowercase y) in their applications. ICU accepts 'Y,' while the Java classes used by V5.3 do not. Therefore, beginning with V5.3, the “Y” character causes an “invalid format” runtime error. (Similarly, the format characters 'u', 'e', 'g' and 'A' that are supported by ICU are also not recognized by the Java classes used in V5.3. However, these are obscure options that are unlikely to be found in typical applications.)
For V5.1 and V5.2, this issue manifests differently. No runtime error occurs, but in the system, the meaning of 'Y' is different from 'y'. In particular, during the first and last weeks of a year (only), 'Y' may return a different value than 'y'.
Example:
- December 31, 2007 formatted with YYYY/MM/dd yields 2008/12/31
- December 31, 2007 formatted with yyyy/MM/dd yields 2007/12/31
The format character 'Y' is intended to be used in conjunction with ISO 8601 "week of year" notation. In every case that was reported, the developer really wanted the value returned by lowercase “y.”
Pegasystems recommends that you review and correct any custom date formats that your applications use, to verify that this issue is not present; it is difficult to discover during routine testing.
Issue: Decimal Precision in Currency
Property values representing money amounts can be formatted for display with the standard HTML Property rule CurrencyAmount. In Version 5.2, this HTML Property rule formats the value using the decimal precision for the currency associated with the property, based on that currency’s ICU standard. For the United States and many other countries, the currency precision is two decimal places; thus, a value of 18.375123 is displayed as “18.38”.
In Version 5.3, due to a side-effect of the replacement of the ICU classes, using CurrencyAmount to format a property displays values using the Java default numeric precision. For example, a currency value is presented with zero to 3 digits after the decimal, so “18.375123” is displayed as “18.375”; “18.00” appears as “18”.
Update: This issue applies to V5.3 only. This issue is not present in Version 5.3SP1, and a correction is available as a hottfix to Version 5.3.
If you modified a copy of the CurrencyAmount HTML property rule, or your applications call the ICU class NumberFormat.setCurrency() method to adjust the decimal precision of formatted output , install the updated pricu2jdk.jar file to restore the correct behavior. The hotfix and Version 5.3 SP1 both include this updated file.