ICU4J Locale Service Provider

Read Me for ICU4J Locale Service Provider

Note: This is a technical preview for ICU4J Locale Service Provider. This component may be changed or removed in future release of ICU4J.

Contents

• Introduction
• Using ICU4J Locale Service Provider
• Optional Configuration
• Building and Testing ICU4J Locale Service Provider

Introduction

Java SE 6 introduced a new feature which allows Java user code to extend locale support in Java runtime environment. JREs shipped by Sun or IBM come with decent locale coverage, but some users may want more locale support. Java SE 6 includes abstract classes extending java.util.spi.LocaleServiceProvider. Java SE 6 users can create a subclass of these abstract class to supply their own locale support for text break, collation, date/number formatting or providing translations for currency, locale and time zone names.

ICU4J has been providing more comprehensive locale coverage than standard JREs. However, Java programmers have to use ICU4J's own internationalization service APIs (com.ibm.icu.*) to utilize the rich locale support. Sometimes, the migration is not an option for various reasons. For example, your code may depend on existing Java libraries utilizing JDK internationalization service APIs, but you have no access to the source code. In this case, it is not possible to modify the libraries to use ICU4J APIs.

ICU4J Locale Service Provider is a component consists of classes implementing the Java SE 6 locale sensitive service provider interfaces. Available service providers are -

• BreakIteratorProvider
• CollatorProvider
• DateFormatProvider
• DateFormatSymbolsProvider
• DecimalFormatSymbolsProvider
• NumberFormatProvider
• CurrencyNameProvider
• LocaleNameProvider
• TimeZoneNameProvider

Using ICU4J Locale Service Provider

Java SE 6 locale sensitive service providers are using the Java Extension Mechanism. An implementation of a locale sensitive service provider is installed as an optional package to extend the functionality of the Java core platform. To install an optional package, its JAR files must be placed in the Java extension directory. The standard location is <java-home>/lib/ext. You can alternatively use the system property java.ext.dirs to specify one or more locations where optional packages are installed. For example, if the JRE root directry is JAVA_HOME and you put ICU4J Locale Service Provider files in ICU_SPI_DIR, the ICU4J Locale Service Provider is enabled by the following command.

  java -Djava.ext.dirs=%JAVA_HOME%\lib\ext;%ICU_SPI_DIR% <your_java_app>  [Microsoft Windows]
  java -Djava.ext.dirs=$JAVA_HOME/lib/ext:$ICU_SPI_DIR <your_java_app>    [Linux, Solaris and other unix like platforms]

The ICU4J's implementations of Java SE 6 locale sensitive service provider interfaces and configuration files are packaged in a single JAR file (icu4j-localespi-<version>.jar). But the actual implementation of the service classes and data are in the ICU4J core JAR file (icu4j-<version>.jar). So you need to put the localespi JAR file along with the core JAR file in the Java extension directory.

Once the ICU4J Locale Service Provider is installed properly, factory methods in JDK internationalization classes look for the implementation provided by ICU4J when a requested locale is not supported by the JDK service class. For example, locale af_ZA (Afrikaans - South Africa) is not supported by JDK DateFormat in Sun Java SE 6. The following code snippet returns an instance of DateFormat from ICU4J Locale Service Provider and prints out the current date localized for af_ZA.

  DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, new Locale("af", "ZA"));
  System.out.println(df.format(new Date()));

  2008 Junie 19     [With ICU4J Locale Service Provider enabled]
  June 19, 2008     [Without ICU4J Locale Service Provider]

Optional Configuration

Enabling or disabling individual service

By default, all Java 6 SE locale sensitive service providers are enabled in the ICU4J Locale Service Provider JAR file. If you want to disable specific providers supported by ICU4J, you can remove the corresponding provider configuration files from META-INF/services in the localespi JAR file. For example, if you do not want to use ICU's time zone name service at all, you can remove the file: META-INF/services/java.util.spi.TimeZoneNameProvider from the JAR file.

Note: Disabling DateFormatSymbolsProvider/DecimalFormatSymbolsProvider won't affect the localized symbols actually used by DateFormatProvider/NumberFormatProvider by the current implementation. These services are implemented independently.

Configuring the behavior of ICU4J Locale Service Provider

com/ibm/icu/impl/javaspi/ICULocaleServiceProviderConfig.properties in the localespi JAR file is used for configuring the behavior of the ICU4J Locale Service Provider implementation. There are some configuration properties available. See the table below for each configuration in detail.

Building and Testing ICU4J Locale Service Provider

ICU4J Locale Service Provider classes depend on the ICU4J core files. To build the component, you should build the ICU4J core JAR file first. Please refer ReadMe for ICU4J to set up the build environment. The actual steps building the ICU4J Locale Service Provider JAR file are described below. The examples used in these steps assume the ICU4J source package is extracted to C:\icu4j on Microsoft Windows.

1. Build the ICU4J core JAR file (icu4j.jar).

  C:\icu4j>ant jar

2. Set JAVA_HOME to JDK 6.0. The ICU4J Locale Service Provider requires JDK 6.0. If you used JDK 6.0 for building the ICU4J core JAR file, this step is not necessary.

  C:\icu4j>set JAVA_HOME=C:\jdk1.6.0

3. Change directory to a subdirectory named "localespi"

4. Run ant with the default target ("jar").

  C:\icu4j\localespi>ant
  Buildfile: build.xml

  check-env-java6:

  icu4j-jar:

  compile:
      [mkdir] Created dir: C:\icu4j\localespi\classes
      [javac] Compiling 22 source files to C:\icu4j\localespi\classes

  jar:
        [jar] Building jar: C:\icu4j\localespi\icu4j-localespi.jar

  build-jar:

  BUILD SUCCESSFUL
  Total time: 5 seconds

With above steps, icu4j-localespi.jar is created in localespi subdirectory. To verify the ICU4J Locale Service Provider component, you can run ant with the target "check". (Note: The target "check" actually creates icu4j-localespi.jar, so you can simply run this target to build and test the component.)

  C:\icu4j\localespi\ant check

     [java] TestAll {
     [java]   BreakIteratorTest {
     [java]     TestGetInstance Passed
     [java]     TestICUEquivalent Passed
     [java]   } Passed
     [java]   CollatorTest {
     [java]     TestGetInstance Passed
     [java]     TestICUEquivalent Passed
     [java]   } Passed
     [java]   CurrencyNameTest {
     [java]     TestCurrencySymbols Passe
     [java]   } Passed
     [java]   DateFormatSymbolsTest {
     [java]     TestGetInstance Passed
     [java]     TestICUEquivalent Passed
     [java]     TestNynorsk Passed
     [java]     TestSetSymbols Passed
     [java]   } Passed
     [java]   DateFormatTest {
     [java]     TestGetInstance Passed
     [java]     TestICUEquivalent Passed
     [java]     TestThaiDigit Passed
     [java]   } Passed
     [java]   DecimalFormatSymbolsTest {
     [java]     TestGetInstance Passed
     [java]     TestICUEquivalent Passed
     [java]     TestSetSymbols Passed
     [java]   } Passed
     [java]   LocaleNameTest {
     [java]     TestCountryNames Passed
     [java]     TestLanguageNames Passed
     [java]     TestVariantNames Passed
     [java]   } Passed
     [java]   NumberFormatTest {
     [java]     TestGetInstance Passed
     [java]     TestICUEquivalent Passed
     [java]   } Passed
     [java]   TimeZoneNameTest {
     [java]     TestTimeZoneNames Passed
     [java]   } Passed
     [java] } Passed

Copyright © 2008-2009 International Business Machines Corporation and others. All Rights Reserved.
4400 North First Street, San José, CA 95193, USA