| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <meta http-equiv="Content-Style-Type" content="text/css2"> |
| <title>ReadMe for ICU4J</title> |
| <meta name="COPYRIGHT" content="© 2016 and later: Unicode, Inc. and others. License & terms of use: http://www.unicode.org/copyright.html"> |
| <style type="text/css"> |
| h2.doc { background: #CCCCFF } |
| h3.doc { text-decoration: underline } |
| </style> |
| </head> |
| <body style="background-color: rgb(255, 255, 255);" lang="EN-US" |
| link="#0000ff" vlink="#800080"> |
| <h1>International Components for Unicode for Java (ICU4J)</h1> |
| <h2>Read Me for ICU4J 68.2</h2> |
| (Last Update: 2020-Dec-02) |
| <hr size="2" width="100%"> |
| |
| <p> |
| <b>Note:</b> This is a major release of ICU4J. It contains bug fixes and adds implementations |
| of inherited API and introduces new API or functionality. |
| <!-- <b>Note:</b> This is a preview release of ICU4J 68. |
| The contents of this document may not reflect the recent changes done |
| for ICU 68 development. It is not recommended for production use. --> |
| <!-- <b>Note:</b> This is a development milestone of ICU4J 68. |
| The contents of this document may not reflect the recent changes done |
| for ICU 68 development. It is not recommended for production use. --> |
| <!-- <b>Note:</b> This is a release candidate of ICU4J 68. |
| The contents of this document may not reflect the recent changes done |
| for ICU 68 development. This release candidate is intended for those |
| wishing to verify ICU 68 integration before final release. It is not |
| recommended for production use. --> |
| </p> |
| <p>For the most recent release, see the <a |
| href="http://www.icu-project.org/download/"> ICU4J |
| download site</a>. </p> |
| <h2 class="doc">Contents</h2> |
| <ul type="disc"> |
| <li><a href="#introduction">Introduction to ICU4J</a></li> |
| <li><a href="#changes">Changes In This Release</a></li> |
| <li><a href="#license">License Information</a></li> |
| <li><a href="#PlatformDependencies">Platform Dependencies</a></li> |
| <li><a href="#download">How to Download ICU4J</a></li> |
| <li><a href="#WhatContain">The Structure and Contents of ICU4J</a></li> |
| <li><a href="#API">Where to Get Documentation</a></li> |
| <li><a href="#HowToInstallJavac">How to Install and Build</a></li> |
| <li><a href="#HowToModularize">How to modularize ICU4J</a></li> |
| <li><a href="#tryingout">Trying Out ICU4J</a></li> |
| <li><a href="#resources">ICU4J Resource Information</a></li> |
| <li><a href="#timezone">About ICU4J Time Zone</a></li> |
| <li><a href="#WhereToFindMore">Where to Find More Information</a></li> |
| <li><a href="#SubmittingComments">Submitting Comments, Requesting |
| Features and Reporting Bugs</a></li> |
| </ul> |
| <h2 class="doc"><a name="introduction"></a>Introduction to ICU4J</h2> |
| <p>The International Components for Unicode (ICU) library provides |
| robust and |
| full-featured Unicode services on a wide variety of platforms. ICU |
| supports the |
| most current version of the Unicode standard, including support for |
| supplementary characters (needed for GB 18030 repertoire support).</p> |
| <p>Java provides a strong foundation for global programs, and IBM and |
| the |
| ICU team played a key role in providing globalization technology to |
| Java. But because of its long release schedule, Java cannot always keep |
| up with evolving standards. The ICU team continues to extend Java's |
| Unicode and internationalization support, focusing on improving |
| performance, |
| keeping current with the Unicode standard, and providing richer APIs, |
| while |
| remaining as compatible as possible with the original Java text and |
| internationalization API design.</p> |
| <p>ICU4J is an add-on to the regular JRE that provides: |
| </p> |
| <ul> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/collation"><b>Collation</b></a> |
| – rule-based, up-to-date Unicode Collation Algorithm (UCA) sorting order<br> |
| For fast multilingual string comparison; faster |
| and more complete than |
| the J2SE implementation</li> |
| <li><a href="https://unicode-org.github.io/icu/userguide/conversion/detection"><b>Charset |
| Detection</b></a> – Recognition of various single and multibyte charsets<br> |
| Useful for recognizing untagged text data</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/strings/unicodeset"><b>UnicodeSet</b></a> |
| – standard set operations optimized for sets of Unicode characters<br> |
| UnicodeSets can be built from string patterns |
| using any Unicode properties.</li> |
| <li><a href="https://unicode-org.github.io/icu/userguide/transforms"><b>Transforms</b></a> |
| – a flexible mechanism for Unicode text conversions<br> |
| Including Full/Halfwidth conversions, |
| Normalization, Case conversions, Hex |
| conversions, and transliterations between scripts (50+ pairs)</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/transforms/normalization"><b>Unicode |
| Normalization</b></a> – NFC, NFD, NFKD, NFKC<br> |
| For canonical text representations, needed for |
| XML and the net</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/datetime/calendar"><b>International |
| Calendars</b></a> – Arabic, Buddhist, Chinese, Hebrew, Japanese, Ethiopic, Islamic, Coptic and other calendars<br> |
| Required for correct presentation of dates in |
| certain countries</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/format_parse/datetime"><b>Date |
| Format |
| Enhancements</b></a> – Date/time pattern generator, Relative date formatting, etc.<br> |
| Enhancements to the normal Java date |
| formatting.</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/format_parse/numbers"><b>Number |
| Format |
| Enhancements</b></a> – Scientific Notation, Spelled-out, Compact decimal format, etc.<br> |
| Enhancements to the normal Java number |
| formatting. The spell-out format is |
| used for checks and similar documents</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/boundaryanalysis"><b>Enhanced |
| Word-Break Detection</b></a> – Rule-based, supports Thai, Khmer, Chinese, etc.<br> |
| Required for correct support of Thai</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/conversion/compression"><b>Unicode |
| Text |
| Compression</b></a> – Standard compression of Unicode text<br> |
| Suitable for large numbers of small fields, |
| where LZW and similar schemes |
| do not apply</li> |
| <li><a |
| href="https://unicode-org.github.io/icu/userguide/conversion"><b>Charset Conversion</b></a> – Conversion to and from different charsets.<br> |
| Plugs into Java CharsetProvider Service Provider Interface (SPI)</li> |
| |
| </ul> |
| <blockquote> |
| <p><b>Note:</b> We continue to provide assistance to Java, and in some |
| cases, ICU4J support has been rolled into a later release of Java. For |
| example, BCP47 language tag support including Unicode locale extensions |
| is now in Java 7. However, the most current and complete version is always |
| found in ICU4J.</p> |
| </blockquote> |
| |
| <h2 class="doc"><a name="changes"></a>Changes In This Release</h2> |
| |
| <p>See the <a href="http://site.icu-project.org/download/68">ICU 68 download page</a> |
| for more informantion about changes in this release.</p> |
| <p>The list of API changes since the previous ICU4J release is available |
| <a href="APIChangeReport.html">here</a>.</p> |
| |
| <h2 class="doc"><a name="license"></a>License Information</h2> |
| <p> |
| The ICU projects (ICU4C and ICU4J) are hosted by the |
| <a href="http://www.unicode.org/">Unicode Consortium</a>. The ICU binary |
| and source files are distributed under the |
| <a href="http://www.unicode.org/copyright.html">UNICODE DATA FILES |
| AND SOFTWARE LICENSE</a>. The full copy of the license and third party |
| software licenses are available in <a href="./main/shared/licenses/LICENSE">LICENSE</a> |
| file included in this package. |
| </p> |
| <h2 class="doc"><a name="PlatformDependencies"></a>Platform Dependencies</h2> |
| <p> |
| The minimum Java runtime version supported by ICU4J 68 is version 7. Java runtime version 6 is not supported. |
| </p> |
| <p> |
| ICU4J since version 63 depend on J2SE 7 functionality. Therefore, ICU4J only runs on |
| JRE version 7 or later. ICU4J 68 is tested on JRE 7, 8, 9, 10 and 11. |
| </p> |
| |
| <h2 class="doc"><a name="download"></a>How to Download ICU4J</h2> |
| <p>There are a few different ways to download the ICU4J releases. |
| </p> |
| <ul type="disc"> |
| <li><b>Official Release:</b><br> |
| If you want to use ICU4J (as opposed to developing it), your best bet |
| is to download an official, packaged version of the ICU4J library files. |
| These versions are tested more thoroughly than day-to-day development |
| builds, and they are packaged in jar files for convenient download. |
| <ul> |
| <li><a href="http://www.icu-project.org/download/">ICU Download page</a>.</li> |
| <li>Maven repository: |
| <pre> |
| <dependency> |
| <groupId>com.ibm.icu</groupId> |
| <artifactId>icu4j</artifactId> |
| <version>68.2</version> |
| </dependency> |
| |
| <dependency> |
| <groupId>com.ibm.icu</groupId> |
| <artifactId>icu4j-charset</artifactId> |
| <version>68.2</version> |
| </dependency> |
| |
| <dependency> |
| <groupId>com.ibm.icu</groupId> |
| <artifactId>icu4j-localespi</artifactId> |
| <version>68.2</version> |
| </dependency> |
| </pre> |
| </ul> |
| </ul> |
| <ul type="disc"> |
| <li><b>GitHub Source Repository:</b><br> |
| If you are interested in developing features, patches, or bug fixes for |
| ICU4J, you should probably be working with the latest version of the |
| ICU4J source code. You will need to clone and checkout the code from our GitHub |
| repository to ensure that you have the most recent version of all of |
| the files. There are several ways to do this. Please follow the |
| directions that are contained on the <a |
| href="http://www.icu-project.org/repository/">Source |
| Repository page</a> for details. |
| </li> |
| </ul> |
| <p>For more details on how to download ICU4J directly from the web |
| site, please see the ICU download page at <a |
| href="http://www.icu-project.org/download/">http://www.icu-project.org/download/</a> |
| </p> |
| <h2 class="doc"><a name="WhatContain"></a>The Structure and Contents of |
| ICU4J</h2> |
| <p>Below, all directory pathes are relative to the directory where the |
| ICU4J source archive is extracted. |
| </p> |
| <p><b>Information and build files:</b></p> |
| <table border="1"> |
| <tr> |
| <th>Path</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>readme.html</td> |
| <td>A description of ICU4J (International Components for Unicode for Java)</td> |
| </tr> |
| <tr> |
| <td>build.html</td> |
| <td>The main Ant build file for ICU4J. See <a href="#HowToInstallJavac">How to Install |
| and Build</a> for more information</td> |
| </tr> |
| <tr> |
| <td>main/shared/licenses/LICENSE</td> |
| <td>ICU license</td> |
| </tr> |
| </table> |
| |
| <p><b>ICU4J runtime class files:</b></p> |
| <table border="1"> |
| <tr> |
| <th>Path</th> |
| <th>Sub-component Name</th> |
| <th>Build Dependencies</th> |
| <th>Public API Packages</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>main/classes/charset</td> |
| <td>icu4j-charset</td> |
| <td>icu4j-core</td> |
| <td>com.ibm.icu.charset</td> |
| <td>Implementation of <code>java.nio.charset.spi.CharsetProvider</code>. |
| This sub-component is shipped as icu4j-charset.jar along with |
| ICU charset converter data files.</td> |
| </tr> |
| <tr> |
| <td>main/classes/collate</td> |
| <td>icu4j-collate</td> |
| <td>icu4j-core</td> |
| <td>com.ibm.icu.text<br> |
| com.ibm.icu.util</td> |
| <td>Collator APIs and implementation. Also includes some public API classes |
| that depend on Collator. |
| This sub-component is packaged as a part of icu4j.jar.</td> |
| </tr> |
| <tr> |
| <td>main/classes/core</td> |
| <td>icu4j-core</td> |
| <td>n/a</td> |
| <td>com.ibm.icu.lang<br> |
| com.ibm.icu.math<br> |
| com.ibm.icu.text<br> |
| com.ibm.icu.util</td> |
| <td>ICU core API classes and implementation. |
| This sub-component is packaged as a part of icu4j.jar.</td> |
| </tr> |
| <tr> |
| <td>main/classes/currdata</td> |
| <td>icu4j-currdata</td> |
| <td>icu4j-core</td> |
| <td>n/a</td> |
| <td>No public API classes. Provides access to currency display data. |
| This sub-component is packaged as a part of icu4j.jar.</td> |
| </tr> |
| <tr> |
| <td>main/classes/langdata</td> |
| <td>icu4j-langdata</td> |
| <td>icu4j-core</td> |
| <td>n/a</td> |
| <td>No public API classes. Provides access to language display data. |
| This sub-component is packaged as a part of icu4j.jar.</td> |
| </tr> |
| <tr> |
| <td>main/classes/localespi</td> |
| <td>icu4j-localespi</td> |
| <td>icu4j-core<br> |
| icu4j-collate<br> |
| </td> |
| <td>n/a</td> |
| <td>Implementation of various locale-sensitive service providers defined |
| in <code>java.text.spi</code> and <code>java.util.spi</code> in J2SE 6.0 |
| or later Java releases. |
| This sub-component is shipped as icu4j-localespi.jar.</td> |
| </tr> |
| <tr> |
| <td>main/classes/regiondata</td> |
| <td>icu4j-regiondata</td> |
| <td>icu4j-core</td> |
| <td>n/a</td> |
| <td>No public API classes. Provides access to region display data. |
| This sub-component is packaged as a part of icu4j.jar.</td> |
| </tr> |
| <tr> |
| <td>main/classes/translit</td> |
| <td>icu4j-translit</td> |
| <td>icu4j-core</td> |
| <td>com.ibm.icu.text</td> |
| <td>Transliterator APIs and implementation. |
| This sub-component is packaged as a part of icu4j.jar.</td> |
| </tr> |
| </table> |
| |
| <p><b>ICU4J unit test files:</b></p> |
| <table border="1"> |
| <tr> |
| <th>Path</th> |
| <th>Sub-component Name</th> |
| <th>Runtime Dependencies</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>main/tests/charset</td> |
| <td>icu4j-charset-tests</td> |
| <td>icu4j-charset<br> |
| icu4j-core<br> |
| icu4j-test-framework</td> |
| <td>Test suite for charset sub-component.</td> |
| </tr> |
| <tr> |
| <td>main/tests/collate</td> |
| <td>icu4j-collate-tests</td> |
| <td>icu4j-collate<br> |
| icu4j-core<br> |
| icu4j-test-framework</td> |
| <td>Test suite for collate sub-component.</td> |
| </tr> |
| <tr> |
| <td>main/tests/core</td> |
| <td>icu4j-core-tests</td> |
| <td>icu4j-core<br> |
| icu4j-currdata<br> |
| icu4j-langdata<br> |
| icu4j-regiondata<br> |
| icu4j-test-framework</td> |
| <td>Test suite for core sub-component.</td> |
| </tr> |
| <tr> |
| <td>main/tests/framework</td> |
| <td>icu4j-test-framework</td> |
| <td>icu4j-core</td> |
| <td>Common ICU4J unit test framework and utilities.</td> |
| </tr> |
| <tr> |
| <td>main/tests/localespi</td> |
| <td>icu4j-localespi-tests</td> |
| <td>icu4j-core<br> |
| icu4j-collate<br> |
| icu4j-currdata<br> |
| icu4j-langdata<br> |
| icu4j-localespi<br> |
| icu4j-regiondata<br> |
| icu4j-test-framework</td> |
| <td>Test suite for localespi sub-component.</td> |
| </tr> |
| <tr> |
| <td>main/tests/packaging</td> |
| <td>icu4j-packaging-tests</td> |
| <td>icu4j-core<br> |
| icu4j-test-framework</td> |
| <td>Test suite for sub-component packaging.</td> |
| </tr> |
| <tr> |
| <td>main/tests/translit</td> |
| <td>icu4j-translit-tests</td> |
| <td>icu4j-core<br> |
| icu4j-translit |
| icu4j-test-framework</td> |
| <td>Test suite for translit sub-component.</td> |
| </tr> |
| </table> |
| |
| <p><b>Others:</b></p> |
| <table border="1"> |
| <tr> |
| <th>Path</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>main/shared</td> |
| <td>Files shared by ICU4J sub-components under the <code>main</code> directory including: |
| <ul> |
| <li>ICU4J runtime data archive (icudata.jar).</li> |
| <li>ICU4J unit test data archive (testdata.jar).</li> |
| <li>Shared Ant build script and configuration files.</li> |
| <li>License files.</li> |
| </ul> |
| </td> |
| </tr> |
| <tr> |
| <td>demos</td> |
| <td>ICU4J demo programs.</td> |
| </tr> |
| <tr> |
| <td>perf-tests</td> |
| <td>ICU4J performance test files.</td> |
| </tr> |
| <tr> |
| <td>tools</td> |
| <td>ICU4J tools including: |
| <ul> |
| <li>Custom JavaDoc taglets used for generating ICU4J API references.</li> |
| <li>API report tool and data.</li> |
| <li>Other independent utilities used for ICU4J development.</li> |
| </ul> |
| </td> |
| </tr> |
| <tr> |
| <td>lib</td> |
| <td>Folder used for downloading depedency libraries.<br> |
| <b>Note:</b> ICU4J runtime libraries do not depend on any external libraries other |
| than JDK. These dependencies are for testing (such as JUnit).</td> |
| </tr> |
| </table> |
| |
| <h2 class="doc"><a name="API"></a>Where to get Documentation</h2> |
| <p>The <a href="https://unicode-org.github.io/icu/userguide/">ICU user's |
| guide</a> contains lots of general information about ICU, in its C, |
| C++, and Java incarnations.</p> |
| <p>The complete API documentation for ICU4J (javadoc) is available on |
| the ICU4J web site, and can be built from the sources: |
| </p> |
| <ul> |
| <li><a href="http://www.icu-project.org/apiref/icu4j/">Index |
| to all ICU4J API</a></li> |
| <li><a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/CharsetDetector.html">Charset Detector</a> – Detection of charset from a byte stream</li> |
| <li>International Calendars – |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/BuddhistCalendar.html">Buddhist</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/ChineseCalendar.html">Chinese</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/CopticCalendar.html">Coptic</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/EthiopicCalendar.html">Ethiopic</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/GregorianCalendar.html">Gregorian</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/HebrewCalendar.html">Hebrew</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/IndianCalendar.html">Indian</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/IslamicCalendar.html">Islamic</a>, |
| <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/JapaneseCalendar.html">Japanese</a>, |
| Persian, Dangi.</li> |
| <li>Time Zone Enhancements – |
| <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/BasicTimeZone.html">Time zone transition and rule detection</a>, |
| <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/VTimeZone.html">iCalendar VTIMEZONE formatting and parsing</a>, |
| <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/RuleBasedTimeZone.html">Custom time zones constructed by user defined rules</a>. |
| <li>Date Format Enhancements – <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/DateTimePatternGenerator.html">Date/Time Pattern Generator</a>, |
| <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/DateIntervalFormat.html">Date Interval Format</a>, |
| <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/DurationFormat.html">Duration Format</a>. |
| <li><a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/Normalizer.html">Unicode |
| Normalization</a> – Canonical text representation for W3C.</li> |
| <li><a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/NumberFormat.html">Number |
| Format Enhancements</a> – Scientific Notation, Spelled out.</li> |
| <li><a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/BreakIterator.html">Enhanced |
| word-break detection</a> – Rule-based, supports Thai</li> |
| <li><a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/Transliterator.html">Transliteration</a> |
| – A general framework for converting text from one format to another, |
| e.g. Cyrillic to Latin, or Hex to Unicode. </li> |
| <li>Unicode Text <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/UnicodeCompressor.html">Compression</a> |
| & <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/UnicodeDecompressor.html">Decompression</a> |
| – 2:1 compression on English Unicode text.</li> |
| <li>Collation – <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/RuleBasedCollator.html">Rule-based |
| sorting</a>, <a |
| href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/StringSearch.html">Efficient |
| multi-lingual searching</a>, |
| <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/AlphabeticIndex.html">Alphabetic indexing</a></li> |
| </ul> |
| <h2 class="doc"><a name="HowToInstallJavac"></a>How to Install and Build</h2> |
| <p> |
| To install ICU4J, simply place the pre-built jar file <strong>icu4j.jar</strong> |
| on your Java CLASSPATH. If you need Charset API support please also place |
| <strong>icu4j-charset.jar</strong> on your class path along with <strong>icu4j.jar</strong>. |
| </p> |
| <p> |
| To build ICU4J, you will need JDK 7 or later (JDK 8 is the reference environment for this release) |
| and the Apache Ant version 1.9 or later. It's recommended to install both the JDK and Ant |
| somewhere <em>outside</em>the ICU4J directory. For example, on Linux you might install |
| these in <code>/usr/local</code>.</p> |
| <ul> |
| <li>Install JDK 8.</li> |
| <li>Install the <a href="http://ant.apache.org/"><strong>Apache Ant</strong></a> |
| 1.9 or later. |
| <li>Set environment variables JAVA_HOME, ANT_HOME and PATH, for example: |
| <pre> |
| set JAVA_HOME=C:\jdk1.8.0 |
| set ANT_HOME=C:\apache-ant |
| set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%</pre> |
| </pre> |
| </li> |
| </ul> |
| <p>Once the JDK and Ant are configured, run the desired target defined in |
| <strong>build.xml</strong>. The default target is "jar" which compiles ICU4J library |
| class files and create ICU4J jar files. For example:</p> |
| <blockquote> |
| <pre>C:\icu4j>ant |
| Buildfile: C:\icu4j\build.xml |
| |
| info: |
| [echo] ----- Build Environment Information ------------------- |
| [echo] Java Home: C:\jdk1.8.0\jre |
| [echo] Java Version: 1.8.0_181 |
| [echo] Ant Home: C:\apache-ant |
| [echo] Ant Version: Apache Ant(TM) version 1.10.1 compiled on February 2 2017 |
| [echo] OS: Windows 10 |
| [echo] OS Version: 10.0 |
| [echo] OS Arch: amd64 |
| [echo] Host: ICUDEV |
| [echo] ------------------------------------------------------- |
| |
| core: |
| |
| @compile: |
| [echo] build-local: ../../shared/../../build-local.properties |
| [echo] --- java compiler arguments ------------------------ |
| [echo] source dir: C:\icu4j\main\classes\core/src |
| [echo] output dir: C:\icu4j\main\classes\core/out/bin |
| [echo] bootclasspath: |
| [echo] classpath: |
| [echo] source: 1.7 |
| [echo] target: 1.7 |
| [echo] debug: on |
| [echo] encoding: UTF-8 |
| [echo] compiler arg: -Xlint:all,-deprecation,-dep-ann,-options,-overrides |
| [echo] ---------------------------------------------------- |
| [mkdir] Created dir: C:\icu4j\main\classes\core\out\bin |
| [javac] Compiling 470 source files to C:\icu4j\main\classes\core\out\bin |
| [javac] Note: Some input files use or override a deprecated API. |
| [javac] Note: Recompile with -Xlint:deprecation for details. |
| |
| compile: |
| |
| @copy: |
| [copy] Copying 24 files to C:\icu4j\main\classes\core\out\bin |
| |
| set-icuconfig-datapath: |
| |
| copy-data: |
| [unjar] Expanding: C:\icu4j\main\shared\data\icudata.jar into C:\icu4j\main\ |
| classes\core\out\bin |
| [unjar] Expanding: C:\icu4j\main\shared\data\icutzdata.jar into C:\icu4j\mai |
| n\classes\core\out\bin |
| |
| ... |
| ... |
| ... |
| |
| localespi: |
| |
| @compile: |
| [echo] build-local: ../../shared/../../build-local.properties |
| [echo] --- java compiler arguments ------------------------ |
| [echo] source dir: C:\icu4j\main\classes\localespi/src |
| [echo] output dir: C:\icu4j\main\classes\localespi/out/bin |
| [echo] bootclasspath: |
| [echo] classpath: C:\icu4j\main\classes\core\out\lib\icu4j-core.jar;C: |
| \icu4j\main\classes\collate\out\lib\icu4j-collate.jar |
| [echo] source: 1.7 |
| [echo] target: 1.7 |
| [echo] debug: on |
| [echo] encoding: UTF-8 |
| [echo] compiler arg: -Xlint:all,-deprecation,-dep-ann,-options |
| [echo] ---------------------------------------------------- |
| [mkdir] Created dir: C:\icu4j\main\classes\localespi\out\bin |
| [javac] Compiling 22 source files to C:\icu4j\main\classes\localespi\out\bin |
| |
| |
| compile: |
| |
| @copy: |
| [copy] Copying 11 files to C:\icu4j\main\classes\localespi\out\bin |
| |
| copy: |
| |
| @jar: |
| [mkdir] Created dir: C:\icu4j\main\classes\localespi\out\lib |
| [copy] Copying 1 file to C:\icu4j\main\classes\localespi\out |
| [jar] Building jar: C:\icu4j\main\classes\localespi\out\lib\icu4j-localesp |
| i.jar |
| |
| jar: |
| |
| @src-jar: |
| [jar] Building jar: C:\icu4j\main\classes\localespi\out\lib\icu4j-localesp |
| i-src.jar |
| |
| src-jar: |
| |
| build: |
| |
| jar: |
| [copy] Copying 1 file to C:\icu4j |
| [copy] Copying 1 file to C:\icu4j |
| |
| BUILD SUCCESSFUL |
| Total time: 30 seconds</pre> |
| </blockquote> |
| <I>Note: The above output is an example. The numbers are likely to be different with the current version ICU4J.</I> |
| <p>The following are some targets that you can provide to <b>ant</b>. |
| For more targets run <code>ant -projecthelp</code> or see the build.xml file.</p> |
| <table border="1"> |
| <tr> |
| <th>jar (default)</th> |
| <td>Create ICU4J runtime library jar archives (<code>icu4j.jar</code>, |
| <code>icu4j-charset.jar</code> and <code>icu4j-localespi.jar</code>) |
| in the root ICU4J directory.</td> |
| </tr> |
| <tr> |
| <th>check</th> |
| <td>Build all ICU4J runtime library classes and corresponding unit test cases, |
| then run the tests.</td> |
| </tr> |
| <tr> |
| <th>clean</th> |
| <td>Remove all build output files.</td> |
| </tr> |
| <tr> |
| <th>main</th> |
| <td>Build all ICU4J runtime library sub-components (under the directory |
| <code>main/classes</code>).</td> |
| </tr> |
| <tr> |
| <th>tests</th> |
| <td>Build all ICU4J unit test sub-components (under the directory <code>main/tests</code>) |
| and their dependencies.</td> |
| </tr> |
| <tr> |
| <th>tools</th> |
| <td>Build the tools.</td> |
| </tr> |
| <tr> |
| <th>docs</th> |
| <td>Run javadoc over the ICU4J runtime library files, generating an HTML documentation |
| tree in the subdirectory <code>doc</code>.</td> |
| </tr> |
| <tr> |
| <th>jarDocs</th> |
| <td>Create ICU4J doc jar archive (<code>icu4jdocs.jar</code>) containing API reference |
| docs in the root ICU4J directory. </td> |
| </tr> |
| <tr> |
| <th>jarDemos</th> |
| <td>Create ICU4J demo jar archive (<code>icu4jdemos.jar</code>) in the root ICU4J |
| directory.</td> |
| </tr> |
| </table> |
| |
| <p>For more information, read the Ant documentation and the <strong>build.xml</strong> |
| file.</p> |
| <p><b>Note:</b> If you get an OutOfMemoryError when you are running <tt>"ant check"</tt>, |
| you can set the heap size of the jvm by setting the environment variable JVM_OPTIONS |
| to the appropriate java options.</p> |
| |
| <p><b>Eclipse users:</b> See the ICU4J site for information on<a |
| href="http://site.icu-project.org/setup/eclipse"> |
| how to configure Eclipse</a> to build and develop ICU4J on Eclipse IDE.</p> |
| |
| <p><b>Note:</b> To install and configure ICU4J Locale Service Provider, please refer the user guide |
| page <a href="https://unicode-org.github.io/icu/userguide/icu4j-locale-service-provider">ICU4J Locale |
| Service Provider</a>.</p> |
| |
| <h2 class="doc"><a name="tryingout"></a>Trying Out ICU4J</h2> |
| <p><strong>Note:</strong> the demos provided with ICU4J are for the |
| most part undocumented. This list can show you where to look, but |
| you'll have to experiment a bit. The demos are <strong>unsupported</strong> |
| and may change or disappear without notice.</p> |
| <p>The icu4j.jar file contains only the ICU4J runtime library classes, not the |
| demo classes, so unless you build ICU4J there is little to try out. |
| </p> |
| <h3 class="doc">Charset</h3> |
| To try out the <strong>Charset</strong> package, build <strong>icu4j.jar</strong> and |
| <strong>icu4j-charset.jar</strong> using the 'jar' target. |
| You can use the charsets by placing these files on your classpath. |
| <blockquote><tt>java -cp $icu4j_root/icu4j.jar:$icu4j_root/icu4j-charset.jar <your program></tt></blockquote> |
| <h3 class="doc">Other demos</h3> |
| <p>The other demo programs are <strong>not supported</strong> and |
| exist only to let you experiment with the ICU4J classes. First, build ICU4J using <tt>ant jarDemos</tt>. |
| Then launch the demos as below:</p> |
| <blockquote><tt>java -jar $icu4j_root/icu4jdemos.jar</tt></blockquote> |
| |
| <h2 class="doc"><a name="resources">ICU4J Resource Information</a></h2> |
| Starting with release 2.1, ICU4J includes its own |
| resource information |
| which is completely independent of the JRE resource information. (Note, |
| ICU4J 2.8 to 3.4, time zone information depends on the underlying JRE). |
| The ICU4J resource information is equivalent to the information in ICU4C and |
| many resources are, in fact, the same binary files that ICU4C uses. |
| <p> |
| By default the ICU4J distribution includes all of the standard resource |
| information. It is located under the directory com/ibm/icu/impl/data. |
| Depending on the service, the data is in different locations and in |
| different formats. <strong>Note:</strong> This will continue to change |
| from release to release, so clients should not depend on the exact |
| organization |
| of the data in ICU4J.</p> |
| <ul> |
| <li>The primary <b>locale data</b> is under the directory <tt>icudt68b</tt>, |
| as a set of <tt>".res"</tt> files whose names are the locale identifiers. |
| Locale naming is documented the <code>com.ibm.icu.util.ULocale</code> |
| class, and the use of these names in searching for resources is documented |
| in <code>com.ibm.icu.util.UResourceBundle</code>.</li> |
| |
| <li>The <b>break iterator data</b> is under the directory <tt>icudt68b/brkitr</tt>, |
| as a set of <tt>".res"</tt>, <tt>".brk"</tt> and <tt>".dict"</tt> files.</li> |
| |
| <li>The <b>collation data</b> is under the directory <tt>icudt68b/coll</tt>, |
| as a set of <tt>".res"</tt> files.</li> |
| |
| <li>The <b>currency display name data</b> is under the directory <tt>icudt68b/curr</tt>, |
| as a set of <tt>".res"</tt> files.</li> |
| |
| <li>The <b>language display name data</b> is under the directory <tt>icudt68b/lang</tt>, |
| as a set of <tt>".res"</tt> files.</li> |
| |
| <li>The <b>rule-based number format data</b> is under the directory |
| <tt>icudt68b/rbnf</tt>, as a set of <tt>".res"</tt> files. |
| |
| <li>The <b>region display name data</b> is under the directory <tt>icudt68b/region</tt>, |
| as a set of <tt>".res"</tt> files.</li> |
| |
| <li>The <b>rule-based transliterator data</b> is under the directory |
| <tt>icudt68b/translit</tt>, as a set of <tt>".res"</tt> files.</li> |
| |
| <li>The <b>measurement unit data</b> is under the directory <tt>icudt68b/unit</tt>, |
| as a set of <tt>".res"</tt> files.</li> |
| |
| <li>The <b>time zone display name data</b> is under the directory |
| <tt>icudt68b/zone</tt>, as a set of <tt>".res"</tt> files.</li> |
| |
| <li>The <b>character property data</b> and default <b>unicode collation algorithm |
| (UCA) data</b> is found under the directory <tt>icudt68b</tt>, as a set of |
| <tt>".icu"</tt> files. </li> |
| |
| <li>The <b>normalization data</b> is found under the directory <tt>icudt68b</tt>, |
| as a set of <tt>".nrm"</tt> files. </li> |
| |
| <li>The <b>character set converter data</b> is under the directory |
| <tt>icudt68b</tt>, as a set of <tt>".cnv"</tt> files. These files are |
| currently included only in icu-charset.jar.</li> |
| |
| <li>The <b>time zone rule data</b> is under the directory |
| <tt>icudt68b</tt>, as <tt>zoneinfo64.res</tt>.</li> |
| |
| <li>The <b>holiday data</b> is under the directory <tt>icudt68b</tt>, |
| as a set of <tt>".class"</tt> files, named <tt>"HolidayBundle_"</tt> |
| followed by the locale ID.</li> |
| |
| </ul> |
| <p> |
| Some of the data files alias or otherwise reference data from other |
| data files. One reason for this is because some locale names have |
| changed. For example, <tt>he_IL</tt> used to be <tt>iw_IL</tt>. In |
| order to support both names but not duplicate the data, one of the |
| resource files refers to the other file's data. In other cases, a |
| file may alias a portion of another file's data in order to save |
| space. Currently ICU4J provides no tool for revealing these |
| dependencies.</p> |
| <blockquote><strong>Note:</strong> Java's <code>Locale</code> class |
| silently converts the language code <tt>"he"</tt> to <tt>"iw"</tt> |
| when you construct the Locale (for versions of Java through Java 5). Thus |
| Java cannot be used to locate resources that use the <tt>"he"</tt> |
| language code. ICU, on the other hand, does not perform this |
| conversion in ULocale, and instead uses aliasing in the locale data to |
| represent the same set of data under different locale |
| ids.</blockquote> |
| <p> |
| Resource files that use locale ids form a hierarchy, with up to four |
| levels: a root, language, region (country), and variant. Searches for |
| locale data attempt to match as far down the hierarchy as possible, |
| for example, <tt>"he_IL"</tt> will match <tt>he_IL</tt>, but |
| <tt>"he_US"</tt> will match <tt>he</tt> (since there is no <tt>US</tt> |
| variant for he, and <tt>"xx_YY</tt> will match root (the |
| default fallback locale) since there is no <tt>xx</tt> language code |
| in the locale hierarchy. Again, see |
| <code>java.util.ResourceBundle</code> for more information. |
| </p> |
| <p> |
| <strong>Currently ICU4J provides no tool for revealing these |
| dependencies</strong> between data files, so trimming the data |
| directly in the ICU4J project is a hit-or-miss affair. The key point |
| when you remove data is to make sure to remove all dependencies on |
| that data as well. For example, if you remove <tt>he.res</tt>, you |
| need to remove <tt>he_IL.res</tt>, since it is lower in the hierarchy, |
| and you must remove iw.res, since it references <tt>he.res</tt>, and |
| <tt>iw_IL.res</tt>, since it depends on it (and also references |
| <tt>he_IL.res</tt>). |
| </p> |
| <p> |
| Unfortunately, the jar tool in the JDK provides no way to remove items |
| from a jar file. Thus you have to extract the resources, remove the |
| ones you don't want, and then create a new jar file with the remining |
| resources. See the jar tool information for how to do this. Before |
| 'rejaring' the files, be sure to thoroughly test your application with |
| the remaining resources, making sure each required resource is |
| present. |
| </p> |
| <h3 class="doc">Using additional resource files with ICU4J</h3> |
| <blockquote> |
| <table cellpadding="3" frame="border" rules="none" width="50%"> |
| <tbody> |
| <tr> |
| <td><b><font color="red" size="+1">Warning:</font> Resource |
| file formats can change across releases of ICU4J!</b></td> |
| </tr> |
| <tr> |
| <td>The format of ICU4J resources is not part of the API. |
| Clients who develop their own resources for use with ICU4J should be |
| prepared to |
| regenerate them when they move to new releases of ICU4J.</td> |
| </tr> |
| </tbody> |
| </table> |
| </blockquote> |
| <p> |
| We are still developing ICU4J's resource mechanism. Currently it |
| is not possible to mix icu's new binary <tt>.res</tt> |
| resources |
| with traditional java-style <tt>.class</tt> or <tt>.txt</tt> |
| resources. We might |
| allow for this in a future release, but since the resource data and |
| format is not formally |
| supported, you run the risk of incompatibilities with future releases |
| of ICU4J. |
| </p> |
| <p> |
| Resource data in ICU4J is checked in to the repository as a jar file |
| containing the resource binaries, <tt>$icu4j_root/main/shared/data/icudata.jar</tt>. |
| This means that inspecting the contents of these resources is difficult. |
| They currently are compiled from ICU4C <tt>.txt</tt> file data. You |
| can view the contents of the ICU4C text resource files to understand |
| the contents of the ICU4J resources. |
| </p> |
| <p> |
| The files in <tt>icudata.jar</tt> get extracted to <tt>com/ibm/icu/impl/data</tt> |
| in the build output directory by some build targets. |
| </p> |
| <h3 class="doc"><a name="resourcesICU4C">Building ICU4J Resources from ICU4C</a></h3> |
| ICU4J data is built by ICU4C tools. Please see "icu4j-readme.txt" in icu4c/source/data for the procedures. |
| <h5> Generating Data from CLDR </h5> |
| <I> Note: This procedure assumes that all 3 sources are present</I> |
| <ol> |
| <li>Checkout or download CLDR version 'release-38'</li> |
| <li>Checkout ICU with tag 'release-68-2'</li> |
| <li>cd to icu4c/source/data directory</li> |
| <li>Follow the instructions in icu4c/source/data/cldr-icu-readme.txt</li> |
| <li>Rebuild ICU4C with the newly generated data.</li> |
| <li>Run ICU4C tests to verify that the new data is good.</li> |
| <li>Build ICU4J data from ICU4C data by following the procedures in icu4j/source/data/icu4j-readme.txt</li> |
| <li>cd to icu4j dir</li> |
| <li>Build and test icu4j</li> |
| </ol> |
| |
| <h2 class="doc"><a name="timezone"></a>About ICU4J Time Zone</h2> |
| <p>ICU4J library includes the latest time zone data, as of the release date. |
| However, time zone data is frequently updated in response |
| to changes made by local governments around the world. If you need to update |
| the time zone data, please refer the ICU user guide topic |
| <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data">Updating the Time Zone Data</a>.</p> |
| <p>You can optionally configure ICU4J date and time |
| service classes to use underlying JDK TimeZone implementation (see the ICU4J API reference |
| <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/TimeZone.html">TimeZone</a> |
| for the details). When this configuration is enabled, ICU's own time zone data |
| won't be used and you have to get time zone data patches from the JRE vendor.</p> |
| |
| <h2 class="doc"><a name="WhereToFindMore"></a>Where to Find More |
| Information</h2> |
| <p><a href="http://www.icu-project.org/">http://www.icu-project.org/</a> |
| is the home page of International Components for Unicode development project</p> |
| |
| <h2 class="doc"><a name="SubmittingComments"></a>Submitting Comments, |
| Requesting Features and |
| Reporting Bugs</h2> |
| <p>Your comments are important to making ICU4J successful. We are |
| committed to investigate any bug reports or suggestions, |
| and will use your feedback to help plan future releases.</p> |
| <p>To submit comments, request features and report bugs, |
| please see <a href="http://www.icu-project.org/bugs.html">ICU bug database |
| information</a> or contact us through the <a |
| href="http://www.icu-project.org/contacts.html">ICU Support |
| mailing list</a>. While we are not able to respond individually to each comment, we do |
| review all comments.</p> |
| <br> |
| <br> |
| <h2>Thank you for your interest in ICU4J!</h2> |
| <br> |
| <hr align="center" size="2" width="100%"> |
| <p><I><font size="-1">© 2016 and later: Unicode, Inc. and others.<br> |
| License & terms of use: <a href="http://www.unicode.org/copyright.html">http://www.unicode.org/copyright.html</a> |
| </font></I></p> |
| </body> |
| </html> |