ICU4JNI: International Components for Unicode for Java Native Interface
ICU4JNI 4.0 ReadMe

Version: 2008-Jul-3
Copyright © 1997-2008 International Business Machines Corporation and others. All Rights Reserved.
Author: Ram Viswanadha, Steven R. Loomis

Contents

• Introduction

• License Information

• System Requirements

• Installation

Introduction

ICU4JNI contains Java Native Interface wrappers for ICU4C's character set conversion and collation libraries.
These wrappers provide increased performace of conversion and collation, and complete compatibility with ICU4C.

License Information

The The X license is a non-viral and recommended free software license that is compatible with the GNU GPL license. The X license is listed as GPL compatible, see the gnu page at http://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses. Please see license.html for text of the license.

System Requirements

• JDK1.3 or above with most recent release updates.

• ICU4C built and installed

Tested Environments

    Note: For running ICU Conversion service with the JDK 1.4 java.nio.charset API, place the icu4jni.jar and ICU4JNIInterface.<dll/so> files in <java_home>/jre/lib/ext/ directory.

Installation

UNIX

1. Download and install ICU4C from http://ibm.com/software/globalization/icu/downloads.jsp

2. Ensure that ICU libraries are available in system's dynamic library search path.

3. Make sure that 'icu-config' is in the system's executable search path defined by PATH environment variable

4. Set the JAVA_HOME environment variable, e.g.:
      export JAVA_HOME=/java/jdk1.3

5. Run configure with prefix and jdk options, ./configure --<enable/disable>-jdk14, e.g.:
      ./configure --prefix=/usr/local/ --enable-jdk14
   ( use the prefix where ICU is installed, and where you may wish icu4jni to be installed )

6. Run make check to build and run tests. Some failures may be due to JDK variants.

7. Binary output is in 'build/lib'.

   
    Note:

• Building ICU4JNI on Solaris need libC.so and libc.so to be present in the search path defined by LD_LIBRARY_PATH environment variable. libC.so should be a symbolic link to libC.so.5

• Building ICU4JNI on AIX, Solaris 64bit requires ICU to be built with --disable-64bit-libraries configure option enabled, as Java is often a 32-bit binary. This may prevent you from using the standard ICU4C binaries.

• For AIX xlC, set the PATH PATH=$PATH:/usr/vacpp/bin to ensure the corect compiler is chosen.

Win32

Make is configured to build with or without JDK 1.4

1. Download and install ICU4C from http://ibm.com/software/globalization/icu/downloads.jsp

2. Set the JAVA_HOME environment variable or pass JAVAPATH on the command line, e.g.:
      set JAVA_HOME=c:\jdk1.3

3. Ensure that the <icu_dir>\bin directory is in your PATH.

4. Ensure that your environment is set right for the C compilation. For Microsoft C compilers, ensure that  vcvars32.bat  has been ran to set the environment variables.

5. Run nmake with the supplied win32 makefile. You can set the configuration option by defining CFG. Also, if ICU_DATA is not set, you can provide the path to the ICU bin directory by defining ICUBIN.

   • To set configuration options define CFG to either Debug or Release, default is Debug

   • If ICU_DATA is not set, define ICUBIN=<icu>/bin

   • The ICU_VERSION is the two-digit version of ICU4C that you are building against, so “40” for ICU 4.0.

For example:
   nmake /f makefile-win32 CFG="Debug" ICUBIN="c:\icu\bin" ICU_VERSION=”40”

For building with JDK 1.4 type the following command

                         nmake /f makefile-win32 CFG="Debug" ICUBIN="<location of ICU>\icu\bin" ICU_VERSION=”40”

For building with JDK1.3 type the following command

                        nmake /f makefile-win32 CFG="Debug" ICUBIN="<location of ICU>\bin" ICU_VERSION=”40” JDK14="FALSE"

6. The files are built in the <jniroot>/build directory. The test is com.ibm.icu4jni.test.TestAll. You must define the library path to point to the jni library, and set the classpath to point to the icu4jni class files. E.g.:
      java -Djava.library.path=c:\icu4jni\build\lib -classpath ;c:\icu4jni\build\classes; com.ibm.icu4jni.test.TestAll
   Alternatively, you can also run the test by making the 'check' target, e.g.:
      <full nmake command as described above> CHECK

For Integrating into JVM only

 * Place the java source files in $(TARGETDIR)/com,i.e, <jdksource>/com
 * Add the following lines to <jdk>/make/mkinclude/java_java.jmk
  $(TARGDIR)com/ibm/icu4jni/ICUJNIInterface.java \
  $(TARGDIR)com/ibm/icu4jni/CharToByteConverterICU.java \
  $(TARGDIR)com/ibm/icu4jni/ByteToCharConverterICU.java \
  # the files below are test classes
  $(TARGDIR)com/ibm/icu4jni/ByteToCharGB18030.java \
  $(TARGDIR)com/ibm/icu4jni/CharToByteGB18030.java \
 * The JNI wrappers work under the assumption that ICU4C is available and installed on the target platform.
 * For adding additional codepages open CharacterEncoding.java in <jdksource>/sun/io directory and add the
   aliases to the converter
  for eg:
  For GB18030 support you add:
  aliasTable.put( "gb18030" , "GB18030");
  aliasTable.put( "gb-18030", "GB18030");
  aliasTable.put( "gb_18030", "GB18030");
  aliasTable.put( "GB-18030", "GB18030");
 * Compile JNI wrapper code into dll/so using a C compiler
 * Package the ICUJNIInterface.dll <jdkbuild>/<platform>/bin directory
 * Rebuild the JDK source