ReadMe: International Components for Unicode for Java

Version: 2.0 December 05 2001

COPYRIGHT:
Copyright (c) 2001 International Business Machines Corporation and others. All Rights Reserved.

Contents

• Introduction to ICU4J (International Components for Unicode for Java)
• License Information
• Platform Dependencies
• How to Download ICU4J
• The Structure and Contents of ICU4J
• Where to Get Documentation
• How to Install and Build
• Trying Out ICU4J
• Where to Find More Information
• Submitting Comments, Requesting Features and Reporting Bugs

Introduction to ICU4J (International Components for Unicode for Java)

Today's global market demands programs that support a wide variety of languages and national conventions.  Customers prefer software and web pages tailored to their needs \226 studies confirm that this leads to increased sales.  Java provides a strong foundation for global programs, and IBM and the ICU4J team played a key role in providing globalization technology to Sun for use in Java.

But Java does not yet provide all the features that some products require.  ICU4J is an add-on library that extends Java's globalization technology by providing the following tools:

• Unicode Normalization – NFC, NFD, NFKD, NFKC

  Produces canonical text representations, needed for XML and the net.

• International Calendars – Arabic, Buddhist, Hebrew, and Japanese

  Required for correct presentation of dates in some countries.

• Number Format Enhancements – Scientific Notation, Spelled-out Numbers

  Enhances standard Java number formatting. The spelled-out format is used for checks and similar documents.

• Enhanced word-break detection – Rule-based, supports Thai

  Required for correct support of Thai.

• Unicode Text Compression – Standard compression of Unicode text

  Suitable for large numbers of small fields, where LZW and similar schemes do not apply.

License Information

The ICU projects (ICU4C and ICU4J) now use the X license.  The X license is a non-viral and recommended free software license that is compatible with the GNU GPL license.  This became effective with release 1.8.1 of ICU4C and release 1.3.1 of ICU4J in mid-2001. All new ICU releases will adopt the X license; previous ICU releases continue to utilize the IPL (IBM Public LIcense).  Users of previous releases of ICU who want to adopt new ICU releases will need to accept the terms and conditions of the X license.

The main effect of the change is to provide GPL compatibility.  The X license is listed as GPL compatible, see the gnu page at http://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses

The text of the X license is available at http://www.x.org/terms.htm. The IBM version contains the essential text of the license, omitting the X-specific trademarks and copyright notices.

For more details please see the press announcement and the Project FAQ.

Platform Dependencies

Parts of ICU4J depend on functionality that is only available in Java2 (JDK1.2) or later, although some components work under 1.1.  However, all components should be compiled using a Java 1.2.x or 1.3.x compiler, as even components that run using a 1.1.x JVM may require language features that are only present in Java2.  Currently 1.1.x is unsupported and untested, and you use the components on a 1.1.x system at your own risk.

ICU4J is currently not compatible with JDK1.4 (in beta as of this writing). We anticipate adding support for JDK1.4 in a future release.

How to Download ICU4J

There are two ways to download the ICU4J releases.

• Official Release Snapshot:
  If you want to use ICU4J (as opposed to developing it), your best bet is to download an official, packaged version of the ICU4J source code.  These versions are tested more thoroughly than day-to-day development builds, and they are packaged in zip files for convenient download.  These packaged files can be found at http://oss.software.ibm.com/icu4j/download/index.html.  If a packaged snapshot is named ICU4JXXXXXX.zip, where XXXXXX is the release version number.  Please unzip this file.  It will reconstruct the source directory.

• CVS Source Repository:
  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 CVS repository to ensure that you have the most recent version of all of the files. There are several ways to do this:
  
  • WebCVS:
    If you want to browse the code and only make occasional downloads, you may want to use WebCVS. It provides a convenient, web-based interface for browsing and downloading the latest version of the ICU4J source code and documentation. You can also view each file's revision history, display the differences between individual revisions, determine which revisions were part of which official release, and so on.
    
  • WinCVS:
    If you will be doing serious work on ICU4J, you should probably install a CVS client on your own machine so that you can do batch operations without going through the WebCVS interface. On Windows, we suggest the WinCVS client. The following is the example instruction on how to download ICU4J via WinCVS:
    1. Install the WinCVS client, which you can download from the http://www.wincvs.org.
    2. Select Preferences from the Admin menu.
       1. On the General tab panel: Set your CVSROOT to ":pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu4j".
          Leave other options on this page at their default.
       2. On the Ports tab panel: Check the pserver checkbox and enter port 2401.
    3. Click on the Login menu button (Admin menu). Enter in "anoncvs" when requested.
    4. To extract the most recent version of ICU4J, select Checkout module from the Create menu. Specify "icu4j" for the module name. This will create a new copy of the workspace on your local hard drive.
    5. In the future, you can download updated files from the repository to your hard drive using the Update selection item in the Modify menu.
       
  • CVS command line:
    You can also check out the repository anonymously on UNIX using the following commands, after first setting your CVSROOT to point to the ICU4J repository:

    export CVSROOT=:pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu4j 
    cvs login CVS password: anoncvs 
    cvs checkout icu4j 
    cvs logout

For more details on how to download ICU4J directly from the web site, please also see http://oss.software.ibm.com/icu4j/download/index.html

The Structure and Contents of ICU4J

Below, $Root is the placement of the icu directory in your file system, like "drive:\...\icu4j" in your environment. "drive:\..." stands for any drive and any directory on that drive that you chose to install icu4j into.

The following files describe the code drop:

The source directories mirror the package structure of the code.  They contain source code and data files:

Building ICU4J creates and populates the following directories:

Data organization:

Data is stored in various locations in ICU4J:

• Data that is "raw" data goes into $Root/src/data. This includes things like the raw Unicode database. $Root/src/data does not contain .java source files.
• Data that is in the form of a Java class, typically (but not necessarily) a ResourceBundle, goes into one of the packages com.ibm.util.resources or com.ibm.text.resources, depending on whether the associated code lives in com.ibm.util or com.ibm.text.
• Data that is not part of ICU4J proper (or its base tool set), but rather part of a test, sample, or demo, should go near the source code of its owner. This makes it easy to ship a core ICU4J release without optional components.

Where to get Documentation

The complete API documentation is available on the ICU4J web site:

• Index to all ICU4J API
• International Calendars – Islamic, Buddhist, Hebrew, Japanese.
• Unicode Normalization – Canonical text representation for W3C.
• Number Format Enhancements – Scientific Notation, Spelled out.
• Enhanced word-break detection – Rule-based, supports Thai
• Unicode Text Searching – Efficient multi-lingual searching.
• Transliteration – A general framework for onverting text from one format to another, e.g. Cyrillic to Latin, or Hex to Unicode.
• Unicode Text Compression & Decompression – 2:1 compression on English Unicode text.

How to Install and Build

To install ICU4J, simply place the prebuilt jar file icu4j.jar on your Java CLASSPATH.  No other files are needed.

To build ICU4J, you will need a Java2 JDK and the Ant build system. We strongly recommend using the Ant build system to build ICU4J:

• It's recommended to install both the JDK and Ant somewhere outside the ICU4J directory. For example, on Linux you might install these in /usr/local.
• Install a recent JDK, version 1.2.x or 1.3.x will work. ICU4J does not yet build with JDK 1.4.

• Next install the Ant build system, part of the Apache Software Foundation's Jakarta project. Ant is a portable, Java-based build system similar to make. ICU4J uses Ant because it introduces no other dependencies, it's portable, and it's easier to manage than a collection of makefiles. We currently build ICU4J using a single makefile on both Windows 9x and Linux using Ant. The build system requires Ant 1.4 or later.

  Installing Ant is straightforward. Download it (see http://jakarta.apache.org/downloads/binindex.html), extract it onto your system, set some environment variables, and add its bin directory to your path. For example:

      set JAVA_HOME=C:\jdk1.3.1
      set ANT_HOME=C:\jakarta-ant
      set PATH=%PATH%;%ANT_HOME%\bin

  See the current Ant documentation for details.

Once the JDK and Ant are installed, building is just a matter of typing ant in the ICU4J root directory. This causes the Ant build system to perform a build as specified by the file build.xml, located in the ICU4J root directory. You can give Ant options like -verbose, and you can specify targets. Ant will only build what's been changed and will resolve dependencies properly. For example:

F:\icu4j>ant tests
Buildfile: build.xml
Project base dir set to: F:\icu4j
Executing Target: core
Compiling 71 source files to F:\icu4j\classes
Executing Target: tests
Compiling 24 source files to F:\icu4j\classes
Completed in 19 seconds

The following are some targets that you can give after ant. For more targets, see the build.xml file:

For more information, read the Ant documentation and the build.xml file.

After doing a build it is a good idea to run all the icu4j tests by typing
"java -classpath $Root/classes -DUnicodeData=$Root/src/data/unicode com.ibm.test.TestAll".

(If you are allergic to build systems, as an alternative to using Ant you can build by running javac and javadoc directly. This is not recommended. You may have to manually create destination directories.)

Trying Out ICU4J

Note: 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 (with the exception of richedit) are unsupported and may change or disappear without notice.

The icu4j.jar file contains only the core ICU4J classes, not the demo classes, so unless you build ICU4J there is little to try out. But you can try out the richedit package, since a GUI is included in the core. To run it, type:

java -classpath icu4j.jar com.ibm.richtext.demo.EditDemo [-swing][file]

You can add tabs to the tab ruler by clicking in the ruler while holding down the control key. Clicking on an existing tab changes between left, right, center, and decimal tabs. Dragging a tab moves it, dragging it off the ruler removes it.

You can experiment with complex text by using the keymap functions. Please note that these are mainly for demo purposes, for real work with Arabic or Hebrew you will want to use an input method. You will need to use a font that supports Arabic or Hebrew, 'Lucida Sans' (provided with Java) supports these languages.

The other demo programs are not supported and exist only to let you experiment with the ICU4J classes. First, build ICU4J using ant all. Then try one of the following:

• java -classpath classes com.ibm.demo.calendar.CalendarApp
• java -classpath classes com.ibm.demo.holiday.HolidayCalendarDemo
• java -classpath classes com.ibm.demo.rbbi.TextBoundDemo
  (Click in the text, then use ctrl-N and ctrl-P to select the next or previous block of text.)
• java -classpath classes com.ibm.demo.rbnf.RbnfDemo
• java -classpath classes com.ibm.demo.translit.Demo

Where to Find More Information

http://oss.software.ibm.com/icu4j is a pointer to general information about the International Components for Unicode in Java

http://www.ibm.com/developer/unicode is a pointer to information on how to make applications global.

Submitting Comments, Requesting Features and Reporting Bugs

Your comments are important to making ICU4J successful.  We are committed to fixing any bugs, and will use your feedback to help plan future releases.

To submit comments, request features and report bugs, contact us through the ICU4J mailing list.
While we are not able to respond individually to each comment, we do review all comments.

Thanks for your interest in ICU4J!

Copyright © 2001 International Business Machines Corporation and others. All Rights Reserved.
10275 N De Anza Blvd., Cupertino, CA 95014