1--- 2layout: default 3title: ICU4J FAQ 4nav_order: 1 5parent: ICU4J 6--- 7<!-- 8© 2020 and later: Unicode, Inc. and others. 9License & terms of use: http://www.unicode.org/copyright.html 10--> 11 12# ICU4J FAQ 13{: .no_toc } 14 15## Contents 16{: .no_toc .text-delta } 17 181. TOC 19{:toc} 20 21--- 22 23# Overview 24 25This page contains frequently asked questions about the content provided with 26the International Components for Unicode for Java as well as basics on 27internationalization. It is organized into the following sections: 28 29### Common Questions 30 31#### What version of Java is required for ICU4J? 32 33ICU4J 4.4 or later versions utilize Java 5 language features and only run on JRE 345 or later. The ICU4J Locale SPI module depends on JDK 6 Locale Service Provider 35framework, therefore, it requires JRE 6 or later. 36 37#### Comparison between ICU and JDK: What's the difference? 38 39This is one of our most popular questions. Please refer to [our comparison 40chart](https://icu.unicode.org/charts/comparison). 41 42#### How can I get the version information of ICU4J library on my system? 43 44You can get the ICU4J version information by public API class 45[com.ibm.icu.util.VersionInfo](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/VersionInfo.html). 46The static field 47[VersionInfo.ICU_VERSION](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/VersionInfo.html#ICU_VERSION) 48contains the current ICU4J library version information. 49Since ICU4J 4.6, ICU4J jar file includes Main-Class that prints out the ICU 50version information like below: 51 52``` 53$ java -jar icu4j.jar 54International Component for Unicode for Java 4.8 55 56Implementation Version: 4.8 57Unicode Data Version: 6.0 58CLDR Data Version: 2.0 59Time Zone Data Version: 2011g 60``` 61 62#### I'm using ICU4J X, but planning to upgrade ICU4J version to X+1 soon. What should I do for the migration? 63 64See the user guide section 65[Version Numbers in ICU](../design#version-numbers-in-icu) 66for the details about the meaning of the version number parts and how the ICU 67version number changes. 68 69In general, two different reference releases are not binary compatible (i.e. 70drop-in jar file replacement would not work). To use a new reference version of 71ICU4J, you should rebuild your application with the new ICU4J library. ICU 72project has the 73[API compatibility policy](../design#icu-api-compatibility) 74long as you're using ICU APIs marked as @stable in the API reference 75documentation, your application should successfully compile with the new 76reference version of ICU4J library without any source code modifications. (Note: 77ICU project team may retract APIs previously marked as @stable by well-defined 78process. But this is a very rare case.) However, you might still need to review 79the usage of ICU4J APIs especially when your application set a certain 80assumption on the behavior of APIs driven by Unicode or locale data. For 81example, a date format pattern used for locale X might not be exactly the same 82with the pattern in a new version. 83 84#### How can I see all API changes between two different ICU versions? 85 86For every ICU4J release, we publish 87[APIChangeReport.html](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/main/icu4j/APIChangeReport.html) 88which captures all API changes since previous reference release. 89However, someone may want to see the changes between the 90current release and much older ICU4J version. For example, you're currently 91using ICU4J 60 and considering to upgrade to ICU4J 64. In this case, you can 92generate a change report page by following steps. 93 941. Download [ICU4J 64 source package 95 archive](https://icu.unicode.org/download/64#TOC-ICU4J-Download) 96 from the ICU 64 download page and extract files to your local system. 972. Set up ICU4J build environment as explained in the 98 [ICU4C Readme](./index). 993. Edit 100 [build.properties](https://github.com/unicode-org/icu/blob/main/icu4j/build.properties) 101 in the root directory and change the property value api.report.prev.version 102 from 63 to 60. 1034. Invoke ant target "apireport". 1045. The output is generated at out/icu4j_compare_60_64.html. 105 106### International Calendars 107 108#### Why do I need these classes? 109 110If your application displays or manipulates dates and times, and if you want 111your application to run in countries outside of North America and western 112Europe, you need to support the traditional calendar systems that are still in 113use in some parts of the world. These classes provide that support while 114conforming to the standard Java Calendar API, allowing you to code your 115application once and have it work with any international calendar. 116 117#### Which Japanese calendar do you support? 118 119Currently, our JapaneseCalendar is almost identical to the Gregorian calendar, 120except that it follows the traditional conventions for year and era names. In 121modern times, each emperor's reign is treated as an era, and years are numbered 122from the start of that era. Historically each emperor's reign would be divided 123up into several eras, or *gengou*. Currently, our era data extends back to 124*Haika*, which began in 645 AD. In all other respects (month and date, all of 125the time fields, etc.) the JapaneseCalendar class will give results that are 126identical to GregorianCalendar. 127 128Lunar calendars similar to the Chinese calendar have also been used in Japan 129during various periods in history, but according to our sources they are not in 130common use today. If you see a real need for a Japanese lunar calendar, and 131especially if you know of any good references on how it differs from the Chinese 132calendar, please let us know by posting a note on the [mailing 133list](https://icu.unicode.org/contacts). 134 135#### Do you *really* support the true lunar Islamic calendar? 136 137The Islamic calendar is strictly lunar, and a month begins at the moment when 138the crescent of the new moon is visible above the horizon at sunset. It is 139impossible to calculate this calendar in advance with 100% accuracy, since moon 140sightings are dependent on the location of the observer, the weather, the 141observer's eyesight, and so on. However, there are fairly commonly-accepted 142criteria (the angle between the sun and the moon, the moon's angle above the 143horizon, the position of the moon's bright limb, etc.) that let you predict the 144start of any given month with a very high degree of accuracy, except of course 145for the weather factor. We currently use a fairly crude approximation that is 146still relatively accurate, corresponding with the official Saudi calendar for 147all but one month in the last 40-odd years. This will be improved in future 148versions of the class. 149 150What all this boils down to is that the IslamicCalendar class does a fairly good 151job of predicting the Islamic calendar, and it is good enough for most 152computational purposes. However, for religious purposes you should, of course, 153consult the appropriate mosque or other authority. 154 155### TimeZone 156 157#### Does ICU4J have its own time zone rule data? 158 159Yes. ICU4J library contains time zone rule data generated from the [tz 160database](https://www.iana.org/time-zones). 161 162#### Why does ICU4J carry the time zone rule data while my JRE also has the data? 163 164There are several reasons. Bundling our own time zone data allow us to provide 165quick updates to users. ICU project team usually release the latest time zone 166rule data patch as soon as the new tz database release is published (usually 167within 1 to 3 days). Having our own rule data also allows the ICU4J library to 168provide some advanced TimeZone features (see [com.ibm.icu.util.BasicTimeZone API 169documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/BasicTimeZone.html)). 170 171#### How can I get the latest time zone rule data patch? 172 173You can use [ICU4J Time Zone Update 174Utility](https://icu.unicode.org/download/icutzu) to update the time zone 175rule data to the latest. 176 177#### I do not want to maintain yet another time zone rule data. Are there any way to configure ICU4J to use the JRE's time zone data? 178 179If you do not use the advanced TimeZone features, then you can configure ICU4J 180to use JRE's time zone support by editing ICUConfig.properties (included in 181ICU4J library jar file) or simply setting a system property. See 182[com.ibm.icu.util.TimeZone API 183documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/TimeZone.html) 184for the details. 185 186### StringSearch 187 188#### Do I have to know anything about Collators to use StringSearch? 189 190Since StringSearch uses a RuleBasedCollator to handle the language-sensitive 191aspects of searching, understanding how collation works certainly helps. But the 192only parts of the Collator API that you really need to know about are the 193collation strength values, `PRIMARY`, `SECONDARY`, and `TERTIARY`, that 194determine whether case and accents are ignored during a search. 195 196#### What algorithm are you using to perform the search? 197 198As of ICU4J 53 / ICU4C 4.0, StringSearch uses a simple linear search algorithm which 199locates a match by shifting a cursor in the target text one by one. Previous 200versions of ICU used a version of the Boyer-Moore search algorithm which was 201modified for use with Unicode. Rather than using raw Unicode character values in 202its comparisons and shift tables, the algorithm uses collation elements that 203have been "hashed" down to a smaller range to make the tables a reasonable size. 204 205### RuleBasedBreakIterator 206 207#### Why did you bother to rewrite BreakIterator? Wasn't the old version working? 208 209It was working, but we were too constrained by the design. The break-data tables 210were hard-coded, and there was only one set of them. This meant you couldn't 211customize BreakIterator's behavior, nor could we accommodate languages with 212mutually-exclusive breaking rules (Japanese and Chinese, for example, have 213different word-breaking rules.) The hard-coded tables were also very 214complicated, difficult to maintain, and easy to mess up, leading to mysterious 215bugs. And in the original version, there was no way to subclass BreakIterator 216and get any implementation at all -- if you wanted different behavior, you had to 217rewrite the whole thing from scratch. We undertook this project to fix all these 218problems and give us a better platform for future development. In addition, we 219managed to get some significant performance improvements out of the new version. 220 221#### What do you mean, performance improvements? It seems WAY slower to me! 222 223The one thing that's significantly slower is construction. This is because it 224actually builds the tables at runtime by parsing a textual description. In the 225old version, the tables were hard-coded, so no initialization was necessary. If 226this is causing you trouble, it's likely that you're creating and destroying 227BreakIterators too frequently. For example, if you're writing code to word-wrap 228a document in a text editor, and you create and destroy a new BreakIterator for 229every line you process, performance will be unbelievably slow. If you move the 230creation out of the inner loop and create a new BreakIterator only once per 231word-wrapping operation, or once per document, you'll find that your performance 232improves dramatically. If you still have problems after doing this, let us 233know -- there may be bugs we need to fix. 234 235#### This still has all the same bugs that the old BreakIterator did! Why would I want to use this one instead? 236 237Because now you can fix it. The resource data in this package was designed to 238mimic as closely as possible the behavior of the original BreakIterator class 239(as of JDK 1.2). We did this deliberately to minimize our variables when making 240sure the new iterator still passed all the old tests. We haven't updated it 241since to avoid the bookkeeping hassles of keeping track of which version 242includes which fixes. We're hoping to get this added to a future version of the 243JDK, at which time we'll fix all the outstanding bugs relating to breaking in 244the wrong places. In the meantime, you can customize the resource data to modify 245things to work the way you want them to. 246 247#### Why is there no demo? 248 249We haven't had time to write a good demo for this new functionality yet. We'll 250add one later. 251 252#### What's this DictionaryBasedBreakIterator thing? 253 254This is a new feature that isn't in the JDK. DictionaryBasedBreakIterator is 255intended for use with languages that don't put spaces between words (such as 256Thai), or for languages that do put spaces between words, but often combine lots 257of words into long compound words (such as German). Instead of looking through 258the text for sequences of characters that signal the end of a word, it compares 259the text against a list of known words, using this to determine where the 260boundaries should go. The algorithm we use for this is fast, accurate, and 261error-tolerant. 262 263#### Why do you have a Thai dictionary, but no resource data that actually lets me use it? 264 265We're not quite done doing the necessary research. We don't currently have good 266test cases we can use to verify it's working correctly with Thai, nor are we 267completely confident in our dictionary. If you can help us with this, we'd like 268to hear from you! 269 270#### What's this BreakIteratorRules_en_US_TEST thing? 271 272This is a resource file that, in conjunction with the "english.dict" dictionary, 273we used to test the dictionary-based break iterator. It allows you to locate 274word boundaries in English text that has had the spaces taken out. (The 275SimpleBITest program demonstrates this.) The dictionary isn't 276industrial-strength, however: we included enough words to make for a reasonable 277test, but it's by no means complete or anywhere near it. 278 279#### How can I create my own dictionary file? 280 281Right now, you can't. We didn't include the tool we used to create dictionary 282files because it's very rough and extremely slow. There's also a strong 283likelihood that the format of the dictionary files will change in the future. If 284you really want to create your own dictionary file, contact us, and we'll see 285what we can do. 286