929 lines
37 KiB
HTML
929 lines
37 KiB
HTML
<!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#License">
|
|
<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 60.1</h2>
|
|
(Last Update: 2017-Oct-30)
|
|
<hr size="2" width="100%">
|
|
|
|
<p>
|
|
<b>Note:</b> This is 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 development milestone of ICU4J 60.
|
|
The contents of this document may not reflect the recent changes done
|
|
for ICU 60 development. It is not recommended for production use. -->
|
|
<!-- <b>Note:</b> This is a release candidate of ICU4J 60.
|
|
The contents of this document may not reflect the recent changes done
|
|
for ICU 60 development. This release candidate is intended for those
|
|
wishing to verify ICU 60 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="http://www.icu-project.org/userguide/Collate_Intro.html"><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="http://www.icu-project.org/userguide/charsetDetection.html"><b>Charset
|
|
Detection</b></a> – Recognition of various single and multibyte charsets<br>
|
|
Useful for recognizing untagged text data</li>
|
|
<li><a
|
|
href="http://www.icu-project.org/userguide/unicodeSet.html"><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="http://www.icu-project.org/userguide/Transform.html"><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="http://www.icu-project.org/userguide/normalization.html"><b>Unicode
|
|
Normalization</b></a> – NFC, NFD, NFKD, NFKC<br>
|
|
For canonical text representations, needed for
|
|
XML and the net</li>
|
|
<li><a
|
|
href="http://www.icu-project.org/userguide/dateCalendar.html"><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="http://www.icu-project.org/userguide/formatNumbers.html"><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="http://www.icu-project.org/userguide/formatNumbers.html"><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="http://www.icu-project.org/userguide/boundaryAnalysis.html"><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="http://www.icu-project.org/userguide/compression.html"><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="http://www.icu-project.org/userguide/conversion.html"><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="https://sites.google.com/site/icusite/download/60">ICU 60 download page</a>
|
|
about new features in this release.</p>
|
|
<p>The list of API changes since the previous ICU4J release is available
|
|
<a href="http://source.icu-project.org/repos/icu/tags/release-60-rc/icu4j/APIChangeReport.html">here</a>.</p>
|
|
|
|
<!-- ICU 60 items -->
|
|
<!-- <h3>[Subject]</h3> -->
|
|
<!-- end ICU 60 items -->
|
|
|
|
<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#License">UNICODE DATA FILES
|
|
AND SOFTWARE LICENSE</a>. The full copy of the license and third party
|
|
software licences 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>
|
|
ICU4J 60 depends on J2SE 6 functionality. Therefore, ICU4J only runs on
|
|
JRE version 6 or later. ICU4J 60 is tested on JRE 6, 7, 8 and 9.
|
|
|
|
<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>60.1</version>
|
|
</dependency>
|
|
|
|
<dependency>
|
|
<groupId>com.ibm.icu</groupId>
|
|
<artifactId>icu4j-charset</artifactId>
|
|
<version>60.1</version>
|
|
</dependency>
|
|
|
|
<dependency>
|
|
<groupId>com.ibm.icu</groupId>
|
|
<artifactId>icu4j-localespi</artifactId>
|
|
<version>60.1</version>
|
|
</dependency>
|
|
</pre>
|
|
</ul>
|
|
</ul>
|
|
<ul type="disc">
|
|
<li><b>Subversion 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 check the code out of our Subversion
|
|
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="http://www.icu-project.org/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 prebuilt 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 envionment 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_144
|
|
[echo] Ant Home: C:\apache-ant
|
|
[echo] Ant Version: Apache Ant(TM) version 1.9.4 compiled on April 29 2014
|
|
|
|
[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.6
|
|
[echo] target: 1.6
|
|
[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 415 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
|
|
[copy] Copied 4 empty directories to 3 empty directories under D:\devicu\ma
|
|
int-60\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
|
|
|
|
...
|
|
...
|
|
...
|
|
|
|
_build-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.6
|
|
[echo] target: 1.6
|
|
[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://www.icu-project.org/docs/eclipse_howto/eclipse_howto.html">
|
|
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="http://userguide.icu-project.org/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>icudt60b</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>icudt60b/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>icudt60b/coll</tt>,
|
|
as a set of <tt>".res"</tt> files.</li>
|
|
|
|
<li>The <b>currency display name data</b> is under the directory <tt>icudt60b/curr</tt>,
|
|
as a set of <tt>".res"</tt> files.</li>
|
|
|
|
<li>The <b>language display name data</b> is under the directory <tt>icudt60b/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>icudt60b/rbnf</tt>, as a set of <tt>".res"</tt> files.
|
|
|
|
<li>The <b>region display name data</b> is under the directory <tt>icudt60b/region</tt>,
|
|
as a set of <tt>".res"</tt> files.</li>
|
|
|
|
<li>The <b>rule-based transliterator data</b> is under the directory
|
|
<tt>icudt60b/translit</tt>, as a set of <tt>".res"</tt> files.</li>
|
|
|
|
<li>The <b>measurement unit data</b> is under the directory <tt>icudt60b/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>icudt60b/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>icudt60b</tt>, as a set of
|
|
<tt>".icu"</tt> files. </li>
|
|
|
|
<li>The <b>normalization data</b> is found under the directory <tt>icudt60b</tt>,
|
|
as a set of <tt>".nrm"</tt> files. </li>
|
|
|
|
<li>The <b>character set converter data</b> is under the directory
|
|
<tt>icudt60b</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>icudt60b</tt>, as <tt>zoneinfo64.res</tt>.</li>
|
|
|
|
<li>The <b>holiday data</b> is under the directory <tt>icudt60b</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-32'</li>
|
|
<li>Checkout ICU with tag 'release-60-1'</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="http://userguide.icu-project.org/datetime/timezone#TOC-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#License">http://www.unicode.org/copyright.html#License</a>
|
|
</font></I></p>
|
|
</body>
|
|
</html>
|