From 2a7120fe5dcf86fd127246e5d75f1ebefb307fd8 Mon Sep 17 00:00:00 2001 From: sreevanis Date: Wed, 24 Feb 2016 17:22:31 -0800 Subject: [PATCH] docs: Added documentation for ICU4J Android Framework. Bug:27076197 Change-Id: I123df56123cbe5e8b5ea16bdf4d7333475617199 --- docs/html/preview/features/icu4j-framework.jd | 175 ++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 docs/html/preview/features/icu4j-framework.jd diff --git a/docs/html/preview/features/icu4j-framework.jd b/docs/html/preview/features/icu4j-framework.jd new file mode 100644 index 0000000000000..895381137b666 --- /dev/null +++ b/docs/html/preview/features/icu4j-framework.jd @@ -0,0 +1,175 @@ +page.title=Using ICU4J Android Framework APIs + +@jd:body + +
+ +
+ +

+ ICU4J is an open-source, widely used set of Java libraries providing Unicode + and globalization support for software applications. The N Developer Preview + exposes a subset of ICU4J APIs in the Android Framework for app developers to + use under the {@code android.icu} package. The ICU4J Android Framework uses + localization data present on the device and can result in a substantial APK + size reduction over apps that include their own copy of ICU4J. +

+ +

+ This document begins by providing some basic information on the minimum + Android API levels required to support these libraries. It then explains what + you need to know about the Android-specific implementation of ICU4J. Finally, + it tells you how to incorporate android.icu APIs into your app. +

+ +

Compatibility Across Android Releases

+ +

+ The ICU4J Android Framework APIs are provided with the N Developer Preview. + If you need to support Android versions prior to the N Developer Preview you + should use the techniques described in Device + Compatibility. +

+ +

Relationship to ICU4J

+ +

+ The N Developer Preview provides a subset of the full ICU4J APIs under the + android.icu package. For example, the N Preview does not expose + some deprecated APIs or those that the ICU team have not yet declared as + stable. As the ICU team deprecates APIs in future, Android will also mark + them as deprecated but will continue to include them. +

+ +

Table 1. ICU and CLDR versions used in the N Developer Preview. + + + + + + + + + + + +
Android API levelICU versionCLDR version
N Developer Preview5628
+ +

+ Note: When using the ICU4J Android Framework APIs you may notice + differences between Android releases. For example, the exact text returned + from formatters may vary between API levels as they do for existing + java.util and java.text classes on Android. These + differences are the result of improvements to translations between Android + versions. +

+ +

Here are a few important things to note:

+ + + +

Migrating to android.icu APIs from ICU4J

+ +

+ If you are already using ICU4J APIs in your app, and the + android.icu APIs meet your requirements, then migrating to + android.icu framework requires you to change your Java imports + from com.ibm.icu to android.icu. You may then + remove your own copy of ICU4J files from the APK. +

+ +

+ Note: The ICU4J Android Framework exposes the classes in the + android.icu + package instead of com.ibm.icu. This is to avoid conflicts with + a copy of ICU4J that may be included in your app’s .apk file. +

+ +

+ Migrating to android.icu APIs from other Android SDK APIs +

+ +

+ Some classes in the java andandroid packages have + equivalents to those found in ICU4J. The ICU4J version often provides more + complete support for standards or a wider range of languages. +

+

Here are some examples to get you started:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ClassAlternatives
java.lang.Character android.icu.lang.UCharacter
java.text.BreakIterator android.icu.text.BreakIterator
java.text.DecimalFormat android.icu.text.DecimalFormat
java.util.Calendar +android.icu.util.Calendar
android.text.BidiFormatter + android.icu.text.Bidi +
android.text.format.DateFormat + android.icu.text.DateFormat +
android.text.format.DateUtils android.icu.text.DateFormat +android.icu.text.RelativeDateTimeFormatter +
+ +

Licensing

+ +

+ ICU4J is released under a nonrestrictive open source + license. +