1--- 2layout: default 3title: ICU4J FAQ 4nav_order: 7 5parent: Misc 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 question. Please refer to [our comparison 40chart](http://icu-project.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/master/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](http://site.icu-project.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 98 [readme.html](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4j/readme.html) 99 included in the root directory of the ICU4J source package archive. 1003. Edit 101 [build.properties](https://github.com/unicode-org/icu/blob/master/icu4j/build.properties) 102 in the root directory and change the property value api.report.prev.version 103 from 63 to 60. 1044. Invoke ant target "apireport". 1055. The output is generated at out/icu4j_compare_60_64.html. 106 107### International Calendars 108 109#### Why do I need these classes? 110 111If your application displays or manipulates dates and times, and if you want 112your application to run in countries outside of North America and western 113Europe, you need to support the traditional calendar systems that are still in 114use in some parts of the world. These classes provide that support while 115conforming to the standard Java Calendar API, allowing you to code your 116application once and have it work with any international calendar. 117 118#### Which Japanese calendar do you support? 119 120Currently, our JapaneseCalendar is almost identical to the Gregorian calendar, 121except that it follows the traditional conventions for year and era names. In 122modern times, each emperor's reign is treated as an era, and years are numbered 123from the start of that era. Historically each emperor's reign would be divided 124up into several eras, or *gengou*. Currently, our era data extends back to 125*Haika*, which began in 645 AD. In all other respects (month and date, all of 126the time fields, etc.) the JapaneseCalendar class will give results that are 127identical to GregorianCalendar. 128 129Lunar calendars similar to the Chinese calendar have also been used in Japan 130during various periods in history, but according to our sources they are not in 131common use today. If you see a real need for a Japanese lunar calendar, and 132especially if you know of any good references on how it differs from the Chinese 133calendar, please let us know by posting a note on the [mailing 134list](http://icu-project.org/contacts.html). 135 136#### Do you *really* support the true lunar Islamic calendar? 137 138The Islamic calendar is strictly lunar, and a month begins at the moment when 139the crescent of the new moon is visible above the horizon at sunset. It is 140impossible to calculate this calendar in advance with 100% accuracy, since moon 141sightings are dependent on the location of the observer, the weather, the 142observer's eyesight, and so on. However, there are fairly commonly-accepted 143criteria (the angle between the sun and the moon, the moon's angle above the 144horizon, the position of the moon's bright limb, etc.) that let you predict the 145start of any given month with a very high degree of accuracy, except of course 146for the weather factor. We currently use a fairly crude approximation that is 147still relatively accurate, corresponding with the official Saudi calendar for 148all but one month in the last 40-odd years. This will be improved in future 149versions of the class. 150 151What all this boils down to is that the IslamicCalendar class does a fairly good 152job of predicting the Islamic calendar, and it is good enough for most 153computational purposes. However, for religious purposes you should, of course, 154consult the appropriate mosque or other authority. 155 156### TimeZone 157 158#### Does ICU4J have its own time zone rule data? 159 160Yes. ICU4J library contains time zone rule data generated from the [tz 161database](https://www.iana.org/time-zones). 162 163#### Why does ICU4J carry the time zone rule data while my JRE also has the data? 164 165There are several reasons. Bundling our own time zone data allow us to provide 166quick updates to users. ICU project team usually release the latest time zone 167rule data patch as soon as the new tz database release is published (usually 168within 1 to 3 days). Having our own rule data also allows the ICU4J library to 169provide some advanced TimeZone features (see [com.ibm.icu.util.BasicTimeZone API 170documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/BasicTimeZone.html)). 171 172#### How can I get the latest time zone rule data patch? 173 174You can use [ICU4J Time Zone Update 175Utility](http://site.icu-project.org/download/icutzu) to update the time zone 176rule data to the latest. 177 178#### 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? 179 180If you do not use the advanced TimeZone features, then you can configure ICU4J 181to use JRE's time zone support by editing ICUConfig.properties (included in 182ICU4J library jar file) or simply setting a system property. See 183[com.ibm.icu.util.TimeZone API 184documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/TimeZone.html) 185for the details. 186 187### StringSearch 188 189#### Do I have to know anything about Collators to use StringSearch? 190 191Since StringSearch uses a RuleBasedCollator to handle the language-sensitive 192aspects of searching, understanding how collation works certainly helps. But the 193only parts of the Collator API that you really need to know about are the 194collation strength values, `PRIMARY`, `SECONDARY`, and `TERTIARY`, that 195determine whether case and accents are ignored during a search. 196 197#### What algorithm are you using to perform the search? 198 199StringSearch uses a version of the Boyer-Moore search algorithm that has been 200modified for use with Unicode. Rather than using raw Unicode character values in 201its comparisons and shift tables, the algorithm uses collation elements that 202have been "hashed" down to a smaller range to make the tables a reasonable size. 203 204### RuleBasedBreakIterator 205 206#### Why did you bother to rewrite BreakIterator? Wasn't the old version working? 207 208It was working, but we were too constrained by the design. The break-data tables 209were hard-coded, and there was only one set of them. This meant you couldn't 210customize BreakIterator's behavior, nor could we accommodate languages with 211mutually-exclusive breaking rules (Japanese and Chinese, for example, have 212different word-breaking rules.) The hard-coded tables were also very 213complicated, difficult to maintain, and easy to mess up, leading to mysterious 214bugs. And in the original version, there was no way to subclass BreakIterator 215and get any implementation at all -- if you wanted different behavior, you had to 216rewrite the whole thing from scratch. We undertook this project to fix all these 217problems and give us a better platform for future development. In addition, we 218managed to get some significant performance improvements out of the new version. 219 220#### What do you mean, performance improvements? It seems WAY slower to me! 221 222The one thing that's significantly slower is construction. This is because it 223actually builds the tables at runtime by parsing a textual description. In the 224old version, the tables were hard-coded, so no initialization was necessary. If 225this is causing you trouble, it's likely that you're creating and destroying 226BreakIterators too frequently. For example, if you're writing code to word-wrap 227a document in a text editor, and you create and destroy a new BreakIterator for 228every line you process, performance will be unbelievably slow. If you move the 229creation out of the inner loop and create a new BreakIterator only once per 230word-wrapping operation, or once per document, you'll find that your performance 231improves dramatically. If you still have problems after doing this, let us 232know -- there may be bugs we need to fix. 233 234#### This still has all the same bugs that the old BreakIterator did! Why would I want to use this one instead? 235 236Because now you can fix it. The resource data in this package was designed to 237mimic as closely as possible the behavior of the original BreakIterator class 238(as of JDK 1.2). We did this deliberately to minimize our variables when making 239sure the new iterator still passed all the old tests. We haven't updated it 240since to avoid the bookkeeping hassles of keeping track of which version 241includes which fixes. We're hoping to get this added to a future version of the 242JDK, at which time we'll fix all the outstanding bugs relating to breaking in 243the wrong places. In the meantime, you can customize the resource data to modify 244things to work the way you want them to. 245 246#### Why is there no demo? 247 248We haven't had time to write a good demo for this new functionality yet. We'll 249add one later. 250 251#### What's this DictionaryBasedBreakIterator thing? 252 253This is a new feature that isn't in the JDK. DictionaryBasedBreakIterator is 254intended for use with languages that don't put spaces between words (such as 255Thai), or for languages that do put spaces between words, but often combine lots 256of words into long compound words (such as German). Instead of looking through 257the text for sequences of characters that signal the end of a word, it compares 258the text against a list of known words, using this to determine where the 259boundaries should go. The algorithm we use for this is fast, accurate, and 260error-tolerant. 261 262#### Why do you have a Thai dictionary, but no resource data that actually lets me use it? 263 264We're not quite done doing the necessary research. We don't currently have good 265test cases we can use to verify it's working correctly with Thai, nor are we 266completely confident in our dictionary. If you can help us with this, we'd like 267to hear from you! 268 269#### What's this BreakIteratorRules_en_US_TEST thing? 270 271This is a resource file that, in conjunction with the "english.dict" dictionary, 272we used to test the dictionary-based break iterator. It allows you to locate 273word boundaries in English text that has had the spaces taken out. (The 274SimpleBITest program demonstrates this.) The dictionary isn't 275industrial-strength, however: we included enough words to make for a reasonable 276test, but it's by no means complete or anywhere near it. 277 278#### How can I create my own dictionary file? 279 280Right now, you can't. We didn't include the tool we used to create dictionary 281files because it's very rough and extremely slow. There's also a strong 282likelihood that the format of the dictionary files will change in the future. If 283you really want to create your own dictionary file, contact us, and we'll see 284what we can do. 285