1--- 2layout: default 3title: ICU4J Locale Service Provider 4nav_order: 7 5parent: ICU 6--- 7<!-- 8© 2020 and later: Unicode, Inc. and others. 9License & terms of use: http://www.unicode.org/copyright.html 10--> 11 12# ICU4J Locale Service Provider 13{: .no_toc } 14 15## Contents 16{: .no_toc .text-delta } 17 181. TOC 19{:toc} 20 21--- 22 23## Overview 24 25Java SE 6 introduced a new feature which allows Java user code to extend locale 26support in Java runtime environment. JREs shipped by Oracle or IBM come with 27decent locale coverage, but some users may want more locale support. Java SE 6 28includes abstract classes extending 29[`java.util.spi.LocaleServiceProvider`](http://download.oracle.com/javase/6/docs/api/java/util/spi/LocaleServiceProvider.html). 30Java SE 6 users can create a subclass of these abstract class to supply their 31own locale support for text break, collation, date/number formatting or 32providing translations for currency, locale and time zone names. 33 34ICU4J has been providing more comprehensive locale coverage than standard JREs. 35However, Java programmers have to use ICU4J's own internationalization service 36APIs (`com.ibm.icu.\*`) to utilize the rich locale support. Sometimes, the 37migration is not an option for various reasons. For example, your code may 38depend on existing Java libraries utilizing JDK internationalization service 39APIs, but you have no access to the source code. In this case, it is not 40possible to modify the libraries to use ICU4J APIs. 41 42ICU4J Locale Service Provider is a component consists of classes implementing 43the Java SE 6 locale sensitive service provider interfaces. Available service 44providers are: 45 46* [`BreakIteratorProvider`](http://download.oracle.com/javase/6/docs/api/java/text/spi/BreakIteratorProvider.html) 47* [`CollatorProvider`](http://download.oracle.com/javase/6/docs/api/java/text/spi/CollatorProvider.html) 48* [`DateFormatProvider`](http://download.oracle.com/javase/6/docs/api/java/text/spi/DateFormatProvider.html) 49* [`DateFormatSymbolsProvider`](http://download.oracle.com/javase/6/docs/api/java/text/spi/DateFormatSymbolsProvider.html) 50* [`DecimalFormatSymbolsProvider`](http://download.oracle.com/javase/6/docs/api/java/text/spi/DecimalFormatSymbolsProvider.html) 51* [`NumberFormatProvider`](http://download.oracle.com/javase/6/docs/api/java/text/spi/NumberFormatProvider.html) 52* [`CurrencyNameProvider`](http://download.oracle.com/javase/6/docs/api/java/util/spi/CurrencyNameProvider.html) 53* [`LocaleNameProvider`](http://download.oracle.com/javase/6/docs/api/java/util/spi/LocaleNameProvider.html) 54* [`TimeZoneNameProvider`](http://download.oracle.com/javase/6/docs/api/java/util/spi/TimeZoneNameProvider.html) 55 56ICU4J Locale Service Provider is designed to work as installed extensions in a 57JRE. Once the component is configured properly, Java application running on the 58JRE automatically picks the ICU4J's internationalization service implementation 59when a requested locale is not available in the JRE. 60 61## Using ICU4J Locale Service Provider 62 63Java SE 6 locale sensitive service providers are using the [Java Extension 64Mechanism](http://download.oracle.com/javase/6/docs/technotes/guides/extensions/index.html). 65An implementation of a locale sensitive service provider is installed as an 66optional package to extend the functionality of the Java core platform. To 67install an optional package, its JAR files must be placed in the Java extension 68directory. The standard location is *<java-home>/lib/ext*. You can alternatively 69use the system property *java.ext.dirs* to specify one or more locations where 70optional packages are installed. For example, if the JRE root directory is 71*JAVA_HOME* and you put ICU4J Locale Service Provider files in *ICU_SPI_DIR*, the 72ICU4J Locale Service Provider is enabled by the following command: 73 74* `java -Djava.ext.dirs=%JAVA_HOME%\\lib\\ext;%ICU_SPI_DIR% <your_java_app>` \[Microsoft Windows\] 75* `java -Djava.ext.dirs=$JAVA_HOME/lib/ext:$ICU_SPI_DIR <your_java_app>` \[Linux,Solaris and other unix like platforms\] 76 77The ICU4J's implementations of Java SE 6 locale sensitive service provider 78interfaces and configuration files are packaged in a single JAR file 79(*icu4j-localespi-<version>.jar*). But the actual implementation of the service 80classes and data are in the ICU4J core JAR file (*icu4j-<version>.jar*). So you 81need to put the localespi JAR file along with the core JAR file in the Java 82extension directory. 83 84Once the ICU4J Locale Service Provider is installed properly, factory methods in 85JDK internationalization classes look for the implementation provided by ICU4J 86when a requested locale is not supported by the JDK service class. For example, 87locale *af_ZA* (Afrikaans - South Africa) is not supported by JDK `DateFormat` in 88Oracle Java SE 6. The following code snippet returns an instance of `DateFormat` 89from ICU4J Locale Service Provider and prints out the current date localized for 90af_ZA. 91 92 DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, new Locale("af", "ZA")); 93 System.out.println(df.format(new Date())); 94 95Sample output: 96 97* `2008 Junie 19` \[With ICU4J Locale Service Provider enabled\] 98* `June 19, 2008` \[Without ICU4J Locale Service Provider\] 99 100## Optional Configuration 101 102### Enabling or disabling individual service 103 104By default, all Java 6 SE locale sensitive service providers are enabled in the 105ICU4J Locale Service Provider JAR file. If you want to disable specific 106providers supported by ICU4J, you can remove the corresponding provider 107configuration files from *META-INF/services* in the localespi JAR file. For 108example, if you do not want to use ICU's time zone name service at all, you can 109remove the file: *META-INF/services/java.util.spi.TimeZoneNameProvider* from the 110JAR file. 111 112**Note:** Disabling `DateFormatSymbolsProvider/DecimalFormatSymbolsProvider` won't 113affect the localized symbols actually used by `DateFormatProvider/NumberFormatProvider` 114by the current implementation. These services are implemented independently. 115 116### Configuring the behavior of ICU4J Locale Service Provider 117 118*com/ibm/icu/impl/javaspi/ICULocaleServiceProviderConfig.properties* in the 119localespi JAR file is used for configuring the behavior of the ICU4J Locale 120Service Provider implementation. There are some configuration properties 121available. See the table below for each configuration in detail. 122 123|**Property**|**Value**|**Default**|**Description**| 124|:---|:---:|:---:|:---| 125|`com.ibm.icu.impl.javaspi.ICULocaleServiceProvider.enableIcuVariants`|`"true"` or `"false"`|`"true"`|Whether if Locales with ICU's variant suffix will be included in `getAvailableLocales`. The current Java SE 6 locale sensitive service does not allow user provided provider implementations to override locales supported by JRE itself. When this property is `"true"` (default), ICU4J Locale Service Provider includes Locales with the suffix (`com.ibm.icu.impl.javaspi.ICULocaleServiceProvider.icuVariantSuffix`) in the variant field. For example, the ICU4J provider includes locales fr_FR and fr_FR_ICU4J in the available locale list. So JDK API user can still access the internationalization service object created by the ICU4J provider by the special locale fr_FR_ICU4J| 126|`com.ibm.icu.impl.javaspi.ICULocaleServiceProvider.icuVariantSuffix`|*Any String*|`"ICU4J"` (49 or later) `"ICU"` (before 49)|Suffix string used in Locale's variant field to specify the ICU implementation.| 127|`com.ibm.icu.impl.javaspi.ICULocaleServiceProvider.enableIso3Languages`|`"true"` or `"false"`|`"true"`|Whether if 3-letter language locales are included in `getAvailableLocales`. Use of 3-letter language codes in `java.util.Locale` is not supported by the API reference document. However, the implementation does not check the length of language code, so there is no practical problem with it.| 128|`com.ibm.icu.impl.javaspi.ICULocaleServiceProvider.useDecimalFormat`|`"true"` or `"false"`|`"false"`|Whether if `java.text.DecimalFormat` subclass is used for `NumberFormat#getXXXInstance`. `DecimalFormat#format(Object,StringBuffer,FieldPosition)` is declared as final, so ICU cannot override the implementation. As a result, some number types such as `BigInteger`/`BigDecimal` are not handled by the ICU implementation. If a client expects `NumberFormat#getXXXInstance` returns a `DecimalFormat` (for example, need to manipulate decimal format patterns), he/she can set true to this setting. However, in this case, `BigInteger`/`BigDecimal` support is not done by ICU's implementation.| 129