Narayan Kamath | 5d1b0c9 | 2014-02-27 14:45:37 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| 2 | "http://www.w3.org/TR/html4/loose.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| 6 | <meta http-equiv="Content-Style-Type" content="text/css2"> |
| 7 | <title>ReadMe for ICU4J</title> |
| 8 | <meta name="COPYRIGHT" content="Copyright 2000-2013, International Business Machines Corporation and others. All Rights Reserved."> |
| 9 | <style type="text/css"> |
| 10 | h3.doc { background: #CCCCFF } |
| 11 | h4.doc { text-decoration: underline } |
| 12 | </style> |
| 13 | </head> |
| 14 | <body style="background-color: rgb(255, 255, 255);" lang="EN-US" |
| 15 | link="#0000ff" vlink="#800080"> |
| 16 | <h2>International Components for Unicode for Java (ICU4J)</h2> |
| 17 | <h3>Read Me for ICU4J 52</h3> |
| 18 | (Last Update: 2013-Oct-07) |
| 19 | <hr size="2" width="100%"> |
| 20 | |
| 21 | <p><b>Note:</b> This is major release of ICU4J. It contains bug fixes and adds implementations |
| 22 | of inherited API and introduces new API or functionality. |
| 23 | </p> |
| 24 | <p>For the most recent release, see the <a |
| 25 | href="http://www.icu-project.org/download/"> ICU4J |
| 26 | download site</a>. </p> |
| 27 | <h3 class="doc">Contents</h3> |
| 28 | <ul type="disc"> |
| 29 | <li><a href="#introduction">Introduction to ICU4J</a></li> |
| 30 | <li><a href="#changes">Changes In This Release</a></li> |
| 31 | <li><a href="#license">License Information</a></li> |
| 32 | <li><a href="#PlatformDependencies">Platform Dependencies</a></li> |
| 33 | <li><a href="#download">How to Download ICU4J</a></li> |
| 34 | <li><a href="#WhatContain">The Structure and Contents of ICU4J</a></li> |
| 35 | <li><a href="#API">Where to Get Documentation</a></li> |
| 36 | <li><a href="#HowToInstallJavac">How to Install and Build</a></li> |
| 37 | <li><a href="#HowToModularize">How to modularize ICU4J</a></li> |
| 38 | <li><a href="#tryingout">Trying Out ICU4J</a></li> |
| 39 | <li><a href="#resources">ICU4J Resource Information</a></li> |
| 40 | <li><a href="#timezone">About ICU4J Time Zone</a></li> |
| 41 | <li><a href="#WhereToFindMore">Where to Find More Information</a></li> |
| 42 | <li><a href="#SubmittingComments">Submitting Comments, Requesting |
| 43 | Features and Reporting Bugs</a></li> |
| 44 | </ul> |
| 45 | <h3 class="doc"><a name="introduction"></a>Introduction to ICU4J</h3> |
| 46 | <p>The International Components for Unicode (ICU) library provides |
| 47 | robust and |
| 48 | full-featured Unicode services on a wide variety of platforms. ICU |
| 49 | supports the |
| 50 | most current version of the Unicode standard, including support for |
| 51 | supplementary characters (needed for GB 18030 repertoire support).</p> |
| 52 | <p>Java provides a strong foundation for global programs, and IBM and |
| 53 | the |
| 54 | ICU team played a key role in providing globalization technology to |
| 55 | Java. But because of its long release schedule, Java cannot always keep |
| 56 | up with evolving standards. The ICU team continues to extend Java's |
| 57 | Unicode and internationalization support, focusing on improving |
| 58 | performance, |
| 59 | keeping current with the Unicode standard, and providing richer APIs, |
| 60 | while |
| 61 | remaining as compatible as possible with the original Java text and |
| 62 | internationalization API design.</p> |
| 63 | <p>ICU4J is an add-on to the regular JRE that provides: |
| 64 | </p> |
| 65 | <ul> |
| 66 | <li><a |
| 67 | href="http://www.icu-project.org/userguide/Collate_Intro.html"><b>Collation</b></a> |
| 68 | – rule-based, up-to-date Unicode Collation Algorithm (UCA) sorting order<br> |
| 69 | For fast multilingual string comparison; faster |
| 70 | and more complete than |
| 71 | the J2SE implementation</li> |
| 72 | <li><a href="http://www.icu-project.org/userguide/charsetDetection.html"><b>Charset |
| 73 | Detection</b></a> – Recognition of various single and multibyte charsets<br> |
| 74 | Useful for recognizing untagged text data</li> |
| 75 | <li><a |
| 76 | href="http://www.icu-project.org/userguide/unicodeSet.html"><b>UnicodeSet</b></a> |
| 77 | – standard set operations optimized for sets of Unicode characters<br> |
| 78 | UnicodeSets can be built from string patterns |
| 79 | using any Unicode properties.</li> |
| 80 | <li><a href="http://www.icu-project.org/userguide/Transform.html"><b>Transforms</b></a> |
| 81 | – a flexible mechanism for Unicode text conversions<br> |
| 82 | Including Full/Halfwidth conversions, |
| 83 | Normalization, Case conversions, Hex |
| 84 | conversions, and transliterations between scripts (50+ pairs)</li> |
| 85 | <li><a |
| 86 | href="http://www.icu-project.org/userguide/normalization.html"><b>Unicode |
| 87 | Normalization</b></a> – NFC, NFD, NFKD, NFKC<br> |
| 88 | For canonical text representations, needed for |
| 89 | XML and the net</li> |
| 90 | <li><a |
| 91 | href="http://www.icu-project.org/userguide/dateCalendar.html"><b>International |
| 92 | Calendars</b></a> – Arabic, Buddhist, Chinese, Hebrew, Japanese, Ethiopic, Islamic, Coptic and other calendars<br> |
| 93 | Required for correct presentation of dates in |
| 94 | certain countries</li> |
| 95 | <li><a |
| 96 | href="http://www.icu-project.org/userguide/formatNumbers.html"><b>Number |
| 97 | Format |
| 98 | Enhancements</b></a> – Scientific Notation, Spelled-out, etc.<br> |
| 99 | Enhancements to the normal Java number |
| 100 | formatting. The spell-out format is |
| 101 | used for checks and similar documents</li> |
| 102 | <li><a |
| 103 | href="http://www.icu-project.org/userguide/boundaryAnalysis.html"><b>Enhanced |
| 104 | Word-Break Detection</b></a> – Rule-based, supports Thai<br> |
| 105 | Required for correct support of Thai</li> |
| 106 | <li><a |
| 107 | href="http://www.icu-project.org/userguide/compression.html"><b>Unicode |
| 108 | Text |
| 109 | Compression</b></a> – Standard compression of Unicode text<br> |
| 110 | Suitable for large numbers of small fields, |
| 111 | where LZW and similar schemes |
| 112 | do not apply</li> |
| 113 | <li><a |
| 114 | href="http://www.icu-project.org/userguide/conversion.html"><b>Charset Conversion</b></a> – Conversion to and from different charsets.<br> |
| 115 | Plugs into Java CharsetProvider Service Provider Interface (SPI)</li> |
| 116 | |
| 117 | </ul> |
| 118 | <blockquote> |
| 119 | <p><b>Note:</b> We continue to provide assistance to Java, and in some |
| 120 | cases, ICU4J support has been rolled into a later release of Java. For |
| 121 | example, BCP47 language tag support including Unicode locale extensions |
| 122 | is now in Java 7. However, the most current and complete version is always |
| 123 | found in ICU4J.</p> |
| 124 | </blockquote> |
| 125 | |
| 126 | <h3 class="doc"><a name="changes"></a>Changes In This Release</h3> |
| 127 | |
| 128 | <p>See the <a href="http://sites.google.com/site/icusite/download/52">ICU 52 download page</a> |
| 129 | about new features in this release. |
| 130 | The list of API changes since the previous ICU4J release is available |
| 131 | <a href="http://source.icu-project.org/repos/icu/icu4j/tags/release-52-1/APIChangeReport.html">here</a>.</p> |
| 132 | |
| 133 | <h3 class="doc"><a name="license"></a>License Information</h3> |
| 134 | <p> |
| 135 | The ICU projects (ICU4C and ICU4J) use the X license. The X |
| 136 | license is <b>suitable for commercial use</b> and is a recommended free software license |
| 137 | that is compatible with the GNU GPL license. This became |
| 138 | effective with release 1.8.1 of ICU4C and release 1.3.1 of ICU4J in |
| 139 | mid-2001. All new ICU releases will adopt the X license; previous ICU |
| 140 | releases continue to utilize the IPL (IBM Public License). Users |
| 141 | of previous releases of ICU who want to adopt new ICU releases will |
| 142 | need to accept the terms and conditions of the X license. |
| 143 | </p> |
| 144 | <p> |
| 145 | The main effect of the change is to provide GPL compatibility. |
| 146 | The X license is listed as GPL compatible, see the GNU page at |
| 147 | <a href="http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses"> |
| 148 | http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses</a>. |
| 149 | This means that GPL projects can now use ICU code, it does <b>not</b> |
| 150 | mean that projects using ICU become subject to GPL. |
| 151 | </p> |
| 152 | <p> |
| 153 | The IBM version contains the essential text of the license, omitting the |
| 154 | X-specific trademarks and copyright notices. The full copy of <a |
| 155 | href="http://source.icu-project.org/repos/icu/icu4j/tags/release-52-1/main/shared/licenses/license.html">ICU's license</a> is included in the download |
| 156 | package. |
| 157 | </p> |
| 158 | <h3 class="doc"><a name="PlatformDependencies"></a>Platform Dependencies</h3> |
| 159 | <p> |
| 160 | ICU4J 52 depends on J2SE 5.0 functionality. Therefore, ICU4J only runs on |
| 161 | JRE version 5.0 or later. |
| 162 | The table below shows the operating systems and JRE/VM versions currently |
| 163 | used by the ICU development team to test ICU4J. |
| 164 | </p> |
| 165 | <table border="1"> |
| 166 | <tr> |
| 167 | <th rowspan="2">Operating System</th> |
| 168 | <th colspan="2">JRE 7</th> |
| 169 | <th colspan="2">JRE 6</th> |
| 170 | <th colspan="2">JRE 5</th> |
| 171 | </tr> |
| 172 | <tr> |
| 173 | <th>32bit</th> |
| 174 | <th>64bit</th> |
| 175 | <th>32bit</th> |
| 176 | <th>64bit</th> |
| 177 | <th>32bit</th> |
| 178 | <th>64bit</th> |
| 179 | </tr> |
| 180 | <tr> |
| 181 | <th>AIX 6.1</th> |
| 182 | <td align="center">-</td> |
| 183 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 184 | <td align="center">-</td> |
| 185 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 186 | <td align="center">-</td> |
| 187 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 188 | </tr> |
| 189 | <tr> |
| 190 | <th>AIX 7.1</th> |
| 191 | <td align="center">-</td> |
| 192 | <td align="center" bgcolor="#CCCCFF"><em><b>Reference platform</b></em></td> |
| 193 | <td align="center">-</td> |
| 194 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 195 | <td align="center">-</td> |
| 196 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 197 | </tr> |
| 198 | <tr> |
| 199 | <th>HP-UX 11 (IA64)</th> |
| 200 | <td align="center">-</td> |
| 201 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 202 | <td align="center">-</td> |
| 203 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 204 | <td align="center">-</td> |
| 205 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 206 | </tr> |
| 207 | <tr> |
| 208 | <th>Mac OS X 10.6</th> |
| 209 | <td align="center">-</td> |
| 210 | <td align="center">-</td> |
| 211 | <td align="center">-</td> |
| 212 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 213 | <td align="center">-</td> |
| 214 | <td align="center">-</td> |
| 215 | </tr> |
| 216 | <tr> |
| 217 | <th>Redhat Enterprise Linux 6 (x86)</th> |
| 218 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 219 | <td align="center">-</td> |
| 220 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 221 | <td align="center">-</td> |
| 222 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 223 | <td align="center">-</td> |
| 224 | </tr> |
| 225 | <tr> |
| 226 | <th>Redhat Enterprise Linux 6 (x86_64)</th> |
| 227 | <td align="center">-</td> |
| 228 | <td align="center" bgcolor="#CCCCFF"><em><b>Reference platform</b></em></td> |
| 229 | <td align="center">-</td> |
| 230 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 231 | <td align="center">-</td> |
| 232 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 233 | </tr> |
| 234 | <tr> |
| 235 | <th>Solaris 10 (SPARC)</th> |
| 236 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 237 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 238 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 239 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 240 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 241 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 242 | </tr> |
| 243 | <tr> |
| 244 | <th>Solaris 11 (SPARC)</th> |
| 245 | <td align="center">-</td> |
| 246 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 247 | <td align="center">-</td> |
| 248 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 249 | <td align="center">-</td> |
| 250 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 251 | </tr> |
| 252 | <tr> |
| 253 | <th>Windows XP</th> |
| 254 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 255 | <td align="center">-</td> |
| 256 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 257 | <td align="center">-</td> |
| 258 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 259 | <td align="center">-</td> |
| 260 | </tr> |
| 261 | <tr> |
| 262 | <th>Windows Vista</th> |
| 263 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 264 | <td align="center">-</td> |
| 265 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 266 | <td align="center">-</td> |
| 267 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 268 | <td align="center">-</td> |
| 269 | </tr> |
| 270 | <tr> |
| 271 | <th>Windows 7</th> |
| 272 | <td align="center" bgcolor="#CCCCFF"><em><b>Reference platform</b></em></td> |
| 273 | <td align="center">-</td> |
| 274 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 275 | <td align="center">-</td> |
| 276 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 277 | <td align="center">-</td> |
| 278 | </tr> |
| 279 | <tr> |
| 280 | <th>Windows 2008 Server</th> |
| 281 | <td align="center">-</td> |
| 282 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 283 | <td align="center">-</td> |
| 284 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 285 | <td align="center">-</td> |
| 286 | <td align="center" bgcolor="#DDDDFF">Regularly tested</td> |
| 287 | </tr> |
| 288 | </table> |
| 289 | |
| 290 | <h3 class="doc"><a name="download"></a>How to Download ICU4J</h3> |
| 291 | <p>There are two ways to download the ICU4J releases. |
| 292 | </p> |
| 293 | <ul type="disc"> |
| 294 | <li><b>Official Release:</b><br> |
| 295 | If you want to use ICU4J (as opposed to developing it), your best bet |
| 296 | is to download an official, packaged version of the ICU4J library files. |
| 297 | These versions are tested more thoroughly than day-to-day development |
| 298 | builds, and they are packaged in jar files for convenient download. |
| 299 | These packaged files can be found at the |
| 300 | <a href="http://www.icu-project.org/download/">ICU Download page</a>. |
| 301 | </li></ul> |
| 302 | <ul type="disc"> |
| 303 | <li><b>Subversion Source Repository:</b><br> |
| 304 | If you are interested in developing features, patches, or bug fixes for |
| 305 | ICU4J, you should probably be working with the latest version of the |
| 306 | ICU4J source code. You will need to check the code out of our Subversion |
| 307 | repository to ensure that you have the most recent version of all of |
| 308 | the files. There are several ways to do this. Please follow the |
| 309 | directions that are contained on the <a |
| 310 | href="http://www.icu-project.org/repository/">Source |
| 311 | Repository page</a> for details. |
| 312 | </li> |
| 313 | </ul> |
| 314 | <p>For more details on how to download ICU4J directly from the web |
| 315 | site, please see the ICU download page at <a |
| 316 | href="http://www.icu-project.org/download/">http://www.icu-project.org/download/</a> |
| 317 | </p> |
| 318 | <h3 class="doc"><a name="WhatContain"></a>The Structure and Contents of |
| 319 | ICU4J</h3> |
| 320 | <p>Below, all directory pathes are relative to the directory where the |
| 321 | ICU4J source archive is extracted. |
| 322 | </p> |
| 323 | <p><b>Information and build files:</b></p> |
| 324 | <table border="1"> |
| 325 | <tr> |
| 326 | <th>Path</th> |
| 327 | <th>Description</th> |
| 328 | </tr> |
| 329 | <tr> |
| 330 | <td>readme.html</td> |
| 331 | <td>A description of ICU4J (International Components for Unicode for Java)</td> |
| 332 | </tr> |
| 333 | <tr> |
| 334 | <td>build.html</td> |
| 335 | <td>The main Ant build file for ICU4J. See <a href="#HowToInstallJavac">How to Install |
| 336 | and Build</a> for more information</td> |
| 337 | </tr> |
| 338 | <tr> |
| 339 | <td>main/shared/licenses/license.html</td> |
| 340 | <td>The X license, used by ICU4J</td> |
| 341 | </tr> |
| 342 | </table> |
| 343 | |
| 344 | <p><b>ICU4J runtime class files:</b></p> |
| 345 | <table border="1"> |
| 346 | <tr> |
| 347 | <th>Path</th> |
| 348 | <th>Sub-component Name</th> |
| 349 | <th>Build Dependencies</th> |
| 350 | <th>Public API Packages</th> |
| 351 | <th>Description</th> |
| 352 | </tr> |
| 353 | <tr> |
| 354 | <td>main/classes/charset</td> |
| 355 | <td>icu4j-charset</td> |
| 356 | <td>icu4j-core</td> |
| 357 | <td>com.ibm.icu.charset</td> |
| 358 | <td>Implementation of <code>java.nio.charset.spi.CharsetProvider</code>. |
| 359 | This sub-component is shipped as icu4j-charset.jar along with |
| 360 | ICU charset converter data files.</td> |
| 361 | </tr> |
| 362 | <tr> |
| 363 | <td>main/classes/collate</td> |
| 364 | <td>icu4j-collate</td> |
| 365 | <td>icu4j-core</td> |
| 366 | <td>com.ibm.icu.text<br> |
| 367 | com.ibm.icu.util</td> |
| 368 | <td>Collator APIs and implementation. Also includes some public API classes |
| 369 | that depend on Collator. |
| 370 | This sub-component is packaged as a part of icu4j.jar.</td> |
| 371 | </tr> |
| 372 | <tr> |
| 373 | <td>main/classes/core</td> |
| 374 | <td>icu4j-core</td> |
| 375 | <td>n/a</td> |
| 376 | <td>com.ibm.icu.lang<br> |
| 377 | com.ibm.icu.math<br> |
| 378 | com.ibm.icu.text<br> |
| 379 | com.ibm.icu.util</td> |
| 380 | <td>ICU core API classes and implementation. |
| 381 | This sub-component is packaged as a part of icu4j.jar.</td> |
| 382 | </tr> |
| 383 | <tr> |
| 384 | <td>main/classes/currdata</td> |
| 385 | <td>icu4j-currdata</td> |
| 386 | <td>icu4j-core</td> |
| 387 | <td>n/a</td> |
| 388 | <td>No public API classes. Provides access to currency display data. |
| 389 | This sub-component is packaged as a part of icu4j.jar.</td> |
| 390 | </tr> |
| 391 | <tr> |
| 392 | <td>main/classes/langdata</td> |
| 393 | <td>icu4j-langdata</td> |
| 394 | <td>icu4j-core</td> |
| 395 | <td>n/a</td> |
| 396 | <td>No public API classes. Provides access to language display data. |
| 397 | This sub-component is packaged as a part of icu4j.jar.</td> |
| 398 | </tr> |
| 399 | <tr> |
| 400 | <td>main/classes/localespi</td> |
| 401 | <td>icu4j-localespi</td> |
| 402 | <td>icu4j-core<br> |
| 403 | icu4j-collate<br> |
| 404 | </td> |
| 405 | <td>n/a</td> |
| 406 | <td>Implementation of various locale-sensitive service providers defined |
| 407 | in <code>java.text.spi</code> and <code>java.util.spi</code> in J2SE 6.0 |
| 408 | or later Java releases. |
| 409 | This sub-component is shipped as icu4j-localespi.jar.</td> |
| 410 | </tr> |
| 411 | <tr> |
| 412 | <td>main/classes/regiondata</td> |
| 413 | <td>icu4j-regiondata</td> |
| 414 | <td>icu4j-core</td> |
| 415 | <td>n/a</td> |
| 416 | <td>No public API classes. Provides access to region display data. |
| 417 | This sub-component is packaged as a part of icu4j.jar.</td> |
| 418 | </tr> |
| 419 | <tr> |
| 420 | <td>main/classes/translit</td> |
| 421 | <td>icu4j-translit</td> |
| 422 | <td>icu4j-core</td> |
| 423 | <td>com.ibm.icu.text</td> |
| 424 | <td>Transliterator APIs and implementation. |
| 425 | This sub-component is packaged as a part of icu4j.jar.</td> |
| 426 | </tr> |
| 427 | </table> |
| 428 | |
| 429 | <p><b>ICU4J unit test files:</b></p> |
| 430 | <table border="1"> |
| 431 | <tr> |
| 432 | <th>Path</th> |
| 433 | <th>Sub-component Name</th> |
| 434 | <th>Runtime Dependencies</th> |
| 435 | <th>Description</th> |
| 436 | </tr> |
| 437 | <tr> |
| 438 | <td>main/tests/charset</td> |
| 439 | <td>icu4j-charset-tests</td> |
| 440 | <td>icu4j-charset<br> |
| 441 | icu4j-core<br> |
| 442 | icu4j-test-framework</td> |
| 443 | <td>Test suite for charset sub-component.</td> |
| 444 | </tr> |
| 445 | <tr> |
| 446 | <td>main/tests/collate</td> |
| 447 | <td>icu4j-collate-tests</td> |
| 448 | <td>icu4j-collate<br> |
| 449 | icu4j-core<br> |
| 450 | icu4j-test-framework</td> |
| 451 | <td>Test suite for collate sub-component.</td> |
| 452 | </tr> |
| 453 | <tr> |
| 454 | <td>main/tests/core</td> |
| 455 | <td>icu4j-core-tests</td> |
| 456 | <td>icu4j-core<br> |
| 457 | icu4j-currdata<br> |
| 458 | icu4j-langdata<br> |
| 459 | icu4j-regiondata<br> |
| 460 | icu4j-test-framework</td> |
| 461 | <td>Test suite for core sub-component.</td> |
| 462 | </tr> |
| 463 | <tr> |
| 464 | <td>main/tests/framework</td> |
| 465 | <td>icu4j-test-framework</td> |
| 466 | <td>icu4j-core</td> |
| 467 | <td>Common ICU4J unit test framework and utilities.</td> |
| 468 | </tr> |
| 469 | <tr> |
| 470 | <td>main/tests/localespi</td> |
| 471 | <td>icu4j-localespi-tests</td> |
| 472 | <td>icu4j-core<br> |
| 473 | icu4j-collate<br> |
| 474 | icu4j-currdata<br> |
| 475 | icu4j-langdata<br> |
| 476 | icu4j-localespi<br> |
| 477 | icu4j-regiondata<br> |
| 478 | icu4j-test-framework</td> |
| 479 | <td>Test suite for localespi sub-component.</td> |
| 480 | </tr> |
| 481 | <tr> |
| 482 | <td>main/tests/packaging</td> |
| 483 | <td>icu4j-packaging-tests</td> |
| 484 | <td>icu4j-core<br> |
| 485 | icu4j-test-framework</td> |
| 486 | <td>Test suite for sub-component packaging.</td> |
| 487 | </tr> |
| 488 | <tr> |
| 489 | <td>main/tests/translit</td> |
| 490 | <td>icu4j-translit-tests</td> |
| 491 | <td>icu4j-core<br> |
| 492 | icu4j-translit |
| 493 | icu4j-test-framework</td> |
| 494 | <td>Test suite for translit sub-component.</td> |
| 495 | </tr> |
| 496 | </table> |
| 497 | |
| 498 | <p><b>Others:</b></p> |
| 499 | <table border="1"> |
| 500 | <tr> |
| 501 | <th>Path</th> |
| 502 | <th>Description</th> |
| 503 | </tr> |
| 504 | <tr> |
| 505 | <td>main/shared</td> |
| 506 | <td>Files shared by ICU4J sub-components under the <code>main</code> directory including: |
| 507 | <ul> |
| 508 | <li>ICU4J runtime data archive (icudata.jar).</li> |
| 509 | <li>ICU4J unit test data archive (testdata.jar).</li> |
| 510 | <li>Shared Ant build script and configuration files.</li> |
| 511 | <li>License files.</li> |
| 512 | </ul> |
| 513 | </td> |
| 514 | </tr> |
| 515 | <tr> |
| 516 | <td>demos</td> |
| 517 | <td>ICU4J demo programs.</td> |
| 518 | </tr> |
| 519 | <tr> |
| 520 | <td>perf-tests</td> |
| 521 | <td>ICU4J performance test files.</td> |
| 522 | </tr> |
| 523 | <tr> |
| 524 | <td>tools</td> |
| 525 | <td>ICU4J tools including: |
| 526 | <ul> |
| 527 | <li>Custom JavaDoc taglets used for generating ICU4J API references.</li> |
| 528 | <li>API report tool and data.</li> |
| 529 | <li>Other independent utilities used for ICU4J development.</li> |
| 530 | </ul> |
| 531 | </td> |
| 532 | </tr> |
| 533 | </table> |
| 534 | |
| 535 | <h3 class="doc"><a name="API"></a>Where to get Documentation</h3> |
| 536 | <p>The <a href="http://www.icu-project.org/userguide/">ICU user's |
| 537 | guide</a> contains lots of general information about ICU, in its C, |
| 538 | C++, and Java incarnations.</p> |
| 539 | <p>The complete API documentation for ICU4J (javadoc) is available on |
| 540 | the ICU4J web site, and can be built from the sources: |
| 541 | </p> |
| 542 | <ul> |
| 543 | <li><a href="http://www.icu-project.org/apiref/icu4j/">Index |
| 544 | to all ICU4J API</a></li> |
| 545 | <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> |
| 546 | <li>International Calendars – |
| 547 | <a |
| 548 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/BuddhistCalendar.html">Buddhist</a>, |
| 549 | <a |
| 550 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/ChineseCalendar.html">Chinese</a>, |
| 551 | <a |
| 552 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/CopticCalendar.html">Coptic</a>, |
| 553 | <a |
| 554 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/EthiopicCalendar.html">Ethiopic</a>, |
| 555 | <a |
| 556 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/GregorianCalendar.html">Gregorian</a>, |
| 557 | <a |
| 558 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/HebrewCalendar.html">Hebrew</a>, |
| 559 | <a |
| 560 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/IndianCalendar.html">Indian</a>, |
| 561 | <a |
| 562 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/IslamicCalendar.html">Islamic</a>, |
| 563 | <a |
| 564 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/JapaneseCalendar.html">Japanese</a>, |
| 565 | Persian, Dangi.</li> |
| 566 | <li>Time Zone Enhancements – |
| 567 | <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/BasicTimeZone.html">Time zone transition and rule detection</a>, |
| 568 | <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/VTimeZone.html">iCalendar VTIMEZONE formatting and parsing</a>, |
| 569 | <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/RuleBasedTimeZone.html">Custom time zones constructed by user defined rules</a>. |
| 570 | <li>Date Format Enhancements – <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/DateTimePatternGenerator.html">Date/Time Pattern Generator</a>, |
| 571 | <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/DateIntervalFormat.html">Date Interval Format</a>, |
| 572 | <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/DurationFormat.html">Duration Format</a>. |
| 573 | <li><a |
| 574 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/Normalizer.html">Unicode |
| 575 | Normalization</a> – Canonical text representation for W3C.</li> |
| 576 | <li><a |
| 577 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/NumberFormat.html">Number |
| 578 | Format Enhancements</a> – Scientific Notation, Spelled out.</li> |
| 579 | <li><a |
| 580 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/BreakIterator.html">Enhanced |
| 581 | word-break detection</a> – Rule-based, supports Thai</li> |
| 582 | <li><a |
| 583 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/Transliterator.html">Transliteration</a> |
| 584 | – A general framework for converting text from one format to another, |
| 585 | e.g. Cyrillic to Latin, or Hex to Unicode. </li> |
| 586 | <li>Unicode Text <a |
| 587 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/UnicodeCompressor.html">Compression</a> |
| 588 | & <a |
| 589 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/UnicodeDecompressor.html">Decompression</a> |
| 590 | – 2:1 compression on English Unicode text.</li> |
| 591 | <li>Collation – <a |
| 592 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/RuleBasedCollator.html">Rule-based |
| 593 | sorting</a>, <a |
| 594 | href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/StringSearch.html">Efficient |
| 595 | multi-lingual searching</a>, |
| 596 | <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/text/AlphabeticIndex.html">Alphabetic indexing</a></li> |
| 597 | </ul> |
| 598 | <h3 class="doc"><a name="HowToInstallJavac"></a>How to Install and Build</h3> |
| 599 | <p> |
| 600 | To install ICU4J, simply place the prebuilt jar file <strong>icu4j.jar</strong> |
| 601 | on your Java CLASSPATH. If you need Charset API support please also place |
| 602 | <strong>icu4j-charset.jar</strong> on your class path along with <strong>icu4j.jar</strong>. |
| 603 | </p> |
| 604 | <p> |
| 605 | To build ICU4J, you will need J2SE SDK 5.0 or later (ICU4J locale SPI |
| 606 | provider sub-components require J2SE SDK 6.0 or later) and the Ant build system |
| 607 | version 1.7 or later. It's recommended to install both the J2SE SDK and Ant |
| 608 | somewhere <em>outside</em>the ICU4J directory. For example, on Linux you might install |
| 609 | these in <code>/usr/local</code>.</p> |
| 610 | <ul> |
| 611 | <li>Install J2SE SDK 7.</li> |
| 612 | <li>Install the <a href="http://ant.apache.org/"><strong>Ant</strong></a> |
| 613 | build system. Ant is a portable, Java-based build system similar to |
| 614 | make. ICU4J uses Ant because it introduces no other dependencies, it's |
| 615 | portable, and it's easier to manage than a collection of makefiles. We |
| 616 | currently build ICU4J using a single makefile on all platforms Ant. |
| 617 | The build system requires Ant 1.7 or later. |
| 618 | <p>Installing Ant is straightforward. Download it (see <a |
| 619 | href="http://ant.apache.org/bindownload.cgi">http://ant.apache.org/bindownload.cgi</a>), |
| 620 | extract it onto your system, set some environment variables, and add |
| 621 | its bin directory to your path. For example: </p> |
| 622 | <pre> |
| 623 | set JAVA_HOME=C:\jdk1.7.0 |
| 624 | set ANT_HOME=C:\ant |
| 625 | set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%</pre> |
| 626 | <p>See the current Ant documentation for details.</p> |
| 627 | </li> |
| 628 | </ul> |
| 629 | <p>Once the J2SE SDK and Ant are installed, building is just a matter of |
| 630 | typing <strong>ant</strong> in the ICU4J root directory. This causes the |
| 631 | Ant build system to perform the build target <strong>jar</strong> |
| 632 | as specified by the file <strong>build.xml</strong>, located in the ICU4J |
| 633 | root directory. You can give Ant options like -verbose, and you can specify |
| 634 | other targets. For example:</p> |
| 635 | <blockquote> |
| 636 | <pre>C:\icu4j>ant |
| 637 | Buildfile: C:\icu4j\build.xml |
| 638 | |
| 639 | info: |
| 640 | [echo] ----- Build Environment Information ------------------- |
| 641 | [echo] Java Home: C:\jdk1.7.0\jre |
| 642 | [echo] Java Version: 1.7.0 |
| 643 | [echo] Ant Home: C:\ant |
| 644 | [echo] Ant Version: Apache Ant(TM) version 1.9.2 compiled on July 8 2013 |
| 645 | [echo] OS: Windows 7 |
| 646 | [echo] OS Version: 6.1 |
| 647 | [echo] OS Arch: amd64 |
| 648 | [echo] Host: ICUDEV |
| 649 | [echo] ------------------------------------------------------- |
| 650 | |
| 651 | core: |
| 652 | |
| 653 | @compile: |
| 654 | [echo] --- java compiler arguments ------------------------ |
| 655 | [echo] source dir: C:\icu4j\main\classes\core/src |
| 656 | [echo] output dir: C:\icu4j\main\classes\core/out/bin |
| 657 | [echo] classpath: |
| 658 | [echo] source: 1.5 |
| 659 | [echo] target: 1.5 |
| 660 | [echo] debug: on |
| 661 | [echo] encoding: UTF-8 |
| 662 | [echo] compiler arg: -Xlint:all,-deprecation,-dep-ann,-options |
| 663 | [echo] ---------------------------------------------------- |
| 664 | [mkdir] Created dir: C:\icu4j\main\classes\core\out\bin |
| 665 | [javac] Compiling 353 source files to C:\icu4j\main\classes\core\out\bin |
| 666 | [javac] Note: Some input files use or override a deprecated API. |
| 667 | [javac] Note: Recompile with -Xlint:deprecation for details. |
| 668 | |
| 669 | compile: |
| 670 | |
| 671 | @copy: |
| 672 | [copy] Copying 23 files to C:\icu4j\main\classes\core\out\bin |
| 673 | |
| 674 | copy-data: |
| 675 | [unjar] Expanding: C:\icu4j\main\shared\data\icudata.jar into C:\icu4j\main\ |
| 676 | classes\core\out\bin |
| 677 | [unjar] Expanding: C:\icu4j\main\shared\data\icutzdata.jar into C:\icu4j\mai |
| 678 | n\classes\core\out\bin |
| 679 | |
| 680 | ... |
| 681 | ... |
| 682 | ... |
| 683 | |
| 684 | _build-localespi: |
| 685 | |
| 686 | @compile: |
| 687 | [echo] --- java compiler arguments ------------------------ |
| 688 | [echo] source dir: C:\icu4j\main\classes\localespi/src |
| 689 | [echo] output dir: C:\icu4j\main\classes\localespi/out/bin |
| 690 | [echo] classpath: C:\icu4j\main\classes\core\out\lib\icu4j-core.jar;C: |
| 691 | \icu4j\main\classes\collate\out\lib\icu4j-collate.jar |
| 692 | [echo] source: 1.6 |
| 693 | [echo] target: 1.6 |
| 694 | [echo] debug: on |
| 695 | [echo] encoding: UTF-8 |
| 696 | [echo] compiler arg: -Xlint:all,-deprecation,-dep-ann,-options |
| 697 | [echo] ---------------------------------------------------- |
| 698 | [mkdir] Created dir: C:\icu4j\main\classes\localespi\out\bin |
| 699 | [javac] Compiling 22 source files to C:\icu4j\main\classes\localespi\out\bin |
| 700 | |
| 701 | |
| 702 | compile: |
| 703 | |
| 704 | @copy: |
| 705 | [copy] Copying 10 files to C:\icu4j\main\classes\localespi\out\bin |
| 706 | |
| 707 | copy: |
| 708 | |
| 709 | @jar: |
| 710 | [mkdir] Created dir: C:\icu4j\main\classes\localespi\out\lib |
| 711 | [copy] Copying 1 file to C:\icu4j\main\classes\localespi\out |
| 712 | [jar] Building jar: C:\icu4j\main\classes\localespi\out\lib\icu4j-localesp |
| 713 | i.jar |
| 714 | |
| 715 | jar: |
| 716 | |
| 717 | @src-jar: |
| 718 | [jar] Building jar: C:\icu4j\main\classes\localespi\out\lib\icu4j-localesp |
| 719 | i-src.jar |
| 720 | |
| 721 | src-jar: |
| 722 | |
| 723 | build: |
| 724 | |
| 725 | jar: |
| 726 | [copy] Copying 1 file to C:\icu4j |
| 727 | [copy] Copying 1 file to C:\icu4j |
| 728 | |
| 729 | BUILD SUCCESSFUL |
| 730 | Total time: 1 minute 51 seconds</pre> |
| 731 | </blockquote> |
| 732 | <I>Note: The above output is an example. The numbers are likely to be different with the current version ICU4J.</I> |
| 733 | <p>The following are some targets that you can provide to <b>ant</b>. |
| 734 | For more targets run <code>ant -projecthelp</code> or see the build.xml file.</p> |
| 735 | <table border="1"> |
| 736 | <tr> |
| 737 | <th>jar (default)</th> |
| 738 | <td>Create ICU4J runtime library jar archives (<code>icu4j.jar</code>, |
| 739 | <code>icu4j-charset.jar</code> and <code>icu4j-localespi.jar</code>) |
| 740 | in the root ICU4J directory.</td> |
| 741 | </tr> |
| 742 | <tr> |
| 743 | <th>check</th> |
| 744 | <td>Build all ICU4J runtime library classes and corresponding unit test cases, |
| 745 | then run the tests.</td> |
| 746 | </tr> |
| 747 | <tr> |
| 748 | <th>clean</th> |
| 749 | <td>Remove all build output files.</td> |
| 750 | </tr> |
| 751 | <tr> |
| 752 | <th>main</th> |
| 753 | <td>Build all ICU4J runtime library sub-components (under the directory |
| 754 | <code>main/classes</code>).</td> |
| 755 | </tr> |
| 756 | <tr> |
| 757 | <th>tests</th> |
| 758 | <td>Build all ICU4J unit test sub-components (under the directory <code>main/tests</code>) |
| 759 | and their dependencies.</td> |
| 760 | </tr> |
| 761 | <tr> |
| 762 | <th>tools</th> |
| 763 | <td>Build the tools.</td> |
| 764 | </tr> |
| 765 | <tr> |
| 766 | <th>docs</th> |
| 767 | <td>Run javadoc over the ICU4J runtime library files, generating an HTML documentation |
| 768 | tree in the subdirectory <code>doc</code>.</td> |
| 769 | </tr> |
| 770 | <tr> |
| 771 | <th>jarDocs</th> |
| 772 | <td>Create ICU4J doc jar archive (<code>icu4jdocs.jar</code>) containing API reference |
| 773 | docs in the root ICU4J directory. </td> |
| 774 | </tr> |
| 775 | <tr> |
| 776 | <th>jarDemos</th> |
| 777 | <td>Create ICU4J demo jar archive (<code>icu4jdemos.jar</code>) in the root ICU4J |
| 778 | directory.</td> |
| 779 | </tr> |
| 780 | </table> |
| 781 | |
| 782 | <p>For more information, read the Ant documentation and the <strong>build.xml</strong> |
| 783 | file.</p> |
| 784 | <p><b>Note:</b> If you get an OutOfMemoryError when you are running <tt>"ant check"</tt>, |
| 785 | you can set the heap size of the jvm by setting the environment variable JVM_OPTIONS |
| 786 | to the appropriate java options.</p> |
| 787 | |
| 788 | <p><b>Eclipse users:</b> See the ICU4J site for information on<a |
| 789 | href="http://www.icu-project.org/docs/eclipse_howto/eclipse_howto.html"> |
| 790 | how to configure Eclipse</a> to build and develop ICU4J on Eclipse IDE.</p> |
| 791 | |
| 792 | <p><b>Note: </b>To install and configure ICU4J Locale Service Provider, please refer the user guide |
| 793 | page <a href="http://userguide.icu-project.org/icu4j-locale-service-provider">ICU4J Locale |
| 794 | Service Provider</a>.</p> |
| 795 | |
| 796 | <h3 class="doc"><a name="HowToModularize"></a>How to modularize ICU4J</h3> |
| 797 | <p>Some clients may not wish to ship all of ICU4J with their |
| 798 | application, since the application might only use a small part of ICU4J. |
| 799 | ICU4J release 2.6 and later provide build options to build individual |
| 800 | ICU4J 'modules' for a more compact distribution. For more details, please |
| 801 | refer to the section <em>Modularization of ICU4J</em> in the ICU user's |
| 802 | guide article <a href="http://userguide.icu-project.org/packaging-icu4j">Packaging ICU4J</a>. |
| 803 | |
| 804 | <h3 class="doc"><a name="tryingout"></a>Trying Out ICU4J</h3> |
| 805 | <p><strong>Note:</strong> the demos provided with ICU4J are for the |
| 806 | most part undocumented. This list can show you where to look, but |
| 807 | you'll have to experiment a bit. The demos are <strong>unsupported</strong> |
| 808 | and may change or disappear without notice.</p> |
| 809 | <p>The icu4j.jar file contains only the ICU4J runtime library classes, not the |
| 810 | demo classes, so unless you build ICU4J there is little to try out. |
| 811 | </p> |
| 812 | <h4>Charset</h4> |
| 813 | To try out the <strong>Charset</strong> package, build <strong>icu4j.jar</strong> and |
| 814 | <strong>icu4j-charset.jar</strong> using the 'jar' target. |
| 815 | You can use the charsets by placing these files on your classpath. |
| 816 | <blockquote><tt>java -cp $icu4j_root/icu4j.jar:$icu4j_root/icu4j-charset.jar <your program></tt></blockquote> |
| 817 | <h4>Other demos</h4> |
| 818 | <p>The other demo programs are <strong>not supported</strong> and |
| 819 | exist only to let you experiment with the ICU4J classes. First, build ICU4J using <tt>ant jarDemos</tt>. |
| 820 | Then launch the demos as below:</p> |
| 821 | <blockquote><tt>java -jar $icu4j_root/icu4jdemos.jar</tt></blockquote> |
| 822 | |
| 823 | <h3 class="doc"><a name="resources">ICU4J Resource Information</a></h3> |
| 824 | Starting with release 2.1, ICU4J includes its own |
| 825 | resource information |
| 826 | which is completely independent of the JRE resource information. (Note, |
| 827 | ICU4J 2.8 to 3.4, time zone information depends on the underlying JRE). |
| 828 | The ICU4J resource information is equivalent to the information in ICU4C and |
| 829 | many resources are, in fact, the same binary files that ICU4C uses. |
| 830 | <p> |
| 831 | By default the ICU4J distribution includes all of the standard resource |
| 832 | information. It is located under the directory com/ibm/icu/impl/data. |
| 833 | Depending on the service, the data is in different locations and in |
| 834 | different formats. <strong>Note:</strong> This will continue to change |
| 835 | from release to release, so clients should not depend on the exact |
| 836 | organization |
| 837 | of the data in ICU4J.</p> |
| 838 | <ul> |
| 839 | <li>The primary <b>locale data</b> is under the directory <tt>icudt52b</tt>, |
| 840 | as a set of <tt>".res"</tt> files whose names are the locale identifiers. |
| 841 | Locale naming is documented the <code>com.ibm.icu.util.ULocale</code> |
| 842 | class, and the use of these names in searching for resources is documented |
| 843 | in <code>com.ibm.icu.util.UResourceBundle</code>.</li> |
| 844 | |
| 845 | <li>The <b>collation data</b> is under the directory <tt>icudt52b/coll</tt>, |
| 846 | as a set of <tt>".res"</tt> files.</li> |
| 847 | |
| 848 | <li>The <b>currency display name data</b> is under the directory <tt>icudt52b/curr</tt>, |
| 849 | as a set of <tt>".res"</tt> files.</li> |
| 850 | |
| 851 | <li>The <b>language display name data</b> is under the directory <tt>icudt52b/lang</tt>, |
| 852 | as a set of <tt>".res"</tt> files.</li> |
| 853 | |
| 854 | <li>The <b>region display name data</b> is under the directory <tt>icudt52b/region</tt>, |
| 855 | as a set of <tt>".res"</tt> files.</li> |
| 856 | |
| 857 | <li>The <b>rule-based transliterator data</b> is under the directory |
| 858 | <tt>icudt52b/translit</tt>, as a set of <tt>".res"</tt> files.</li> |
| 859 | |
| 860 | <li>The <b>rule-based number format data</b> is under the directory |
| 861 | <tt>icudt52b/rbnf</tt>, as a set of <tt>".res"</tt> files. |
| 862 | |
| 863 | <li>The <b>break iterator data</b> is directly under the |
| 864 | directory <tt>icudt52b</tt>, as a set of <tt>".brk"</tt> files, named according to the |
| 865 | type of break and the locale where there are locale-specific versions.</li> |
| 866 | |
| 867 | <li>The <b>holiday data</b> is under the directory <tt>icudt52b</tt>, |
| 868 | as a set of <tt>".class"</tt> files, named <tt>"HolidayBundle_"</tt> |
| 869 | followed by the locale ID.</li> |
| 870 | |
| 871 | <li>The <b>character property data</b> and default <b>unicode collation algorithm |
| 872 | (UCA) data</b> is found under the directory <tt>icudt52b</tt>, as a set of |
| 873 | <tt>".icu"</tt> files. </li> |
| 874 | |
| 875 | <li>The <b>normalization data</b> is found under the directory <tt>icudt52b</tt>, |
| 876 | as a set of <tt>".nrm"</tt> files. </li> |
| 877 | |
| 878 | <li>The <b>character set converter data</b> is under the directory |
| 879 | <tt>icudt52b</tt>, as a set of <tt>".cnv"</tt> files. These files are |
| 880 | currently included only in icu-charset.jar.</li> |
| 881 | |
| 882 | <li>The <b>time zone rule data</b> is under the directory |
| 883 | <tt>icudt52b</tt>, as <tt>zoneinfo64.res</tt>.</li> |
| 884 | |
| 885 | <li>The <b>time zone display name data</b> is under the directory |
| 886 | <tt>icudt52b/zone</tt>, as a set of <tt>".res"</tt> files.</li> |
| 887 | </ul> |
| 888 | <p> |
| 889 | Some of the data files alias or otherwise reference data from other |
| 890 | data files. One reason for this is because some locale names have |
| 891 | changed. For example, <tt>he_IL</tt> used to be <tt>iw_IL</tt>. In |
| 892 | order to support both names but not duplicate the data, one of the |
| 893 | resource files refers to the other file's data. In other cases, a |
| 894 | file may alias a portion of another file's data in order to save |
| 895 | space. Currently ICU4J provides no tool for revealing these |
| 896 | dependencies.</p> |
| 897 | <blockquote><strong>Note:</strong> Java's <code>Locale</code> class |
| 898 | silently converts the language code <tt>"he"</tt> to <tt>"iw"</tt> |
| 899 | when you construct the Locale (for versions of Java through Java 5). Thus |
| 900 | Java cannot be used to locate resources that use the <tt>"he"</tt> |
| 901 | language code. ICU, on the other hand, does not perform this |
| 902 | conversion in ULocale, and instead uses aliasing in the locale data to |
| 903 | represent the same set of data under different locale |
| 904 | ids.</blockquote> |
| 905 | <p> |
| 906 | Resource files that use locale ids form a hierarchy, with up to four |
| 907 | levels: a root, language, region (country), and variant. Searches for |
| 908 | locale data attempt to match as far down the hierarchy as possible, |
| 909 | for example, <tt>"he_IL"</tt> will match <tt>he_IL</tt>, but |
| 910 | <tt>"he_US"</tt> will match <tt>he</tt> (since there is no <tt>US</tt> |
| 911 | variant for he, and <tt>"xx_YY</tt> will match root (the |
| 912 | default fallback locale) since there is no <tt>xx</tt> language code |
| 913 | in the locale hierarchy. Again, see |
| 914 | <code>java.util.ResourceBundle</code> for more information. |
| 915 | </p> |
| 916 | <p> |
| 917 | <strong>Currently ICU4J provides no tool for revealing these |
| 918 | dependencies</strong> between data files, so trimming the data |
| 919 | directly in the ICU4J project is a hit-or-miss affair. The key point |
| 920 | when you remove data is to make sure to remove all dependencies on |
| 921 | that data as well. For example, if you remove <tt>he.res</tt>, you |
| 922 | need to remove <tt>he_IL.res</tt>, since it is lower in the hierarchy, |
| 923 | and you must remove iw.res, since it references <tt>he.res</tt>, and |
| 924 | <tt>iw_IL.res</tt>, since it depends on it (and also references |
| 925 | <tt>he_IL.res</tt>). |
| 926 | </p> |
| 927 | <p> |
| 928 | Unfortunately, the jar tool in the JDK provides no way to remove items |
| 929 | from a jar file. Thus you have to extract the resources, remove the |
| 930 | ones you don't want, and then create a new jar file with the remining |
| 931 | resources. See the jar tool information for how to do this. Before |
| 932 | 'rejaring' the files, be sure to thoroughly test your application with |
| 933 | the remaining resources, making sure each required resource is |
| 934 | present. |
| 935 | </p> |
| 936 | <h4>Using additional resource files with ICU4J</h4> |
| 937 | <blockquote> |
| 938 | <table cellpadding="3" frame="border" rules="none" width="50%"> |
| 939 | <tbody> |
| 940 | <tr> |
| 941 | <td><b><font color="red" size="+1">Warning:</font> Resource |
| 942 | file formats can change across releases of ICU4J!</b></td> |
| 943 | </tr> |
| 944 | <tr> |
| 945 | <td>The format of ICU4J resources is not part of the API. |
| 946 | Clients who develop their own resources for use with ICU4J should be |
| 947 | prepared to |
| 948 | regenerate them when they move to new releases of ICU4J.</td> |
| 949 | </tr> |
| 950 | </tbody> |
| 951 | </table> |
| 952 | </blockquote> |
| 953 | <p> |
| 954 | We are still developing ICU4J's resource mechanism. Currently it |
| 955 | is not possible to mix icu's new binary <tt>.res</tt> |
| 956 | resources |
| 957 | with traditional java-style <tt>.class</tt> or <tt>.txt</tt> |
| 958 | resources. We might |
| 959 | allow for this in a future release, but since the resource data and |
| 960 | format is not formally |
| 961 | supported, you run the risk of incompatibilities with future releases |
| 962 | of ICU4J. |
| 963 | </p> |
| 964 | <p> |
| 965 | Resource data in ICU4J is checked in to the repository as a jar file |
| 966 | containing the resource binaries, <tt>$icu4j_root/main/shared/data/icudata.jar</tt>. |
| 967 | This means that inspecting the contents of these resources is difficult. |
| 968 | They currently are compiled from ICU4C <tt>.txt</tt> file data. You |
| 969 | can view the contents of the ICU4C text resource files to understand |
| 970 | the contents of the ICU4J resources. |
| 971 | </p> |
| 972 | <p> |
| 973 | The files in <tt>icudata.jar</tt> get extracted to <tt>com/ibm/icu/impl/data</tt> |
| 974 | in the build output directory by some build targets. |
| 975 | </p> |
| 976 | <h4><a name="resourcesICU4C">Building ICU4J Resources from ICU4C</a></h4> |
| 977 | ICU4J data is built by ICU4C tools. Please see "icu4j-readme.txt" in <I>$icu4c_root</I>/source/data for the procedures. |
| 978 | <h5> Generating Data from CLDR </h5> |
| 979 | <I> Note: This procedure assumes that all 3 sources are present</I> |
| 980 | <ol> |
| 981 | <li>Checkout or download CLDR version 'release-24'</li> |
| 982 | <li>Checkout ICU4C with tag 'release-52-1'</li> |
| 983 | <li>Checkout ICU4J with tag 'release-52-1'</li> |
| 984 | <li>cd to <I>$icu4c_root</I>/source/data directory</li> |
| 985 | <li>Follow the instructions in <I>$icu4c_root</I>/source/data/cldr-icu-readme.txt</li> |
| 986 | <li>Rebuild ICU4C with the newly generated data.</li> |
| 987 | <li>Run ICU4C tests to verify that the new data is good.</li> |
| 988 | <li>Build ICU4J data from ICU4C data by following the procedures in <I>$icu4c_root</I>/source/data/icu4j-readme.txt</li> |
| 989 | <li>cd to <I>$icu4j_root</I> dir</li> |
| 990 | |
| 991 | <li>Build and test icu4j</li> |
| 992 | </ol> |
| 993 | |
| 994 | <h3 class="doc"><a name="timezone"></a>About ICU4J Time Zone</h3> |
| 995 | <p>ICU4J 52.1 includes time zone data version 2013g, which is the latest one as of |
| 996 | the release date. However, time zone data is frequently updated in response |
| 997 | to changes made by local governments around the world. If you need to update |
| 998 | the time zone data, please refer the ICU user guide topic |
| 999 | <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">Updating the Time Zone Data</a>.</p> |
| 1000 | <p>Starting with ICU4J 4.0, you can optionally configure ICU4J date and time |
| 1001 | service classes to use underlying JDK TimeZone implementation (see the ICU4J API reference |
| 1002 | <a href="http://www.icu-project.org/apiref/icu4j/com/ibm/icu/util/TimeZone.html">TimeZone</a> |
| 1003 | for the details). When this configuration is enabled, ICU's own time zone data |
| 1004 | won't be used and you have to get time zone data patches from the JRE vendor.</p> |
| 1005 | |
| 1006 | <h3 class="doc"><a name="WhereToFindMore"></a>Where to Find More |
| 1007 | Information</h3> |
| 1008 | <p><a href="http://www.icu-project.org/">http://www.icu-project.org/</a> |
| 1009 | is the home page of International Components for Unicode development project</p> |
| 1010 | <p><a href="http://www.ibm.com/software/globalization/icu/">http://www.ibm.com/software/globalization/icu/</a> |
| 1011 | is a pointer to general information about the International Components for |
| 1012 | Unicode hosted by IBM</p> |
| 1013 | <p><a href="http://www.ibm.com/software/globalization/">http://www.ibm.com/software/globalization/</a> |
| 1014 | is a pointer to |
| 1015 | information on how to make applications global. </p> |
| 1016 | <h3 class="doc"><a name="SubmittingComments"></a>Submitting Comments, |
| 1017 | Requesting Features and |
| 1018 | Reporting Bugs</h3> |
| 1019 | <p>Your comments are important to making ICU4J successful. We are |
| 1020 | committed to investigate any bug reports or suggestions, |
| 1021 | and will use your feedback to help plan future releases.</p> |
| 1022 | <p>To submit comments, request features and report bugs, |
| 1023 | please see <a href="http://www.icu-project.org/bugs.html">ICU bug database |
| 1024 | information</a> or contact us through the <a |
| 1025 | href="http://www.icu-project.org/contacts.html">ICU Support |
| 1026 | mailing list</a>. While we are not able to respond individually to each comment, we do |
| 1027 | review all comments.</p> |
| 1028 | <br> |
| 1029 | <br> |
| 1030 | <h2>Thank you for your interest in ICU4J!</h2> |
| 1031 | <br> |
| 1032 | <hr align="center" size="2" width="100%"> |
| 1033 | <p><I><font size="-1">Copyright © 2002-2013 International Business |
| 1034 | Machines Corporation and others. All Rights |
| 1035 | Reserved.<br> |
| 1036 | 4400 North First Street, San José, CA 95193, USA |
| 1037 | </font></I></p> |
| 1038 | </body> |
| 1039 | </html> |