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. +
+ ++ 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. +
+ +
+ 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 level | +ICU version | +CLDR version | +
|---|---|---|
| N Developer Preview | +56 | +28 | +
+ 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:
+ +
+ 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.
+
+ 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:
+| Class | +Alternatives | +
|---|---|
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
+ |
+
+ ICU4J is released under a nonrestrictive open source + license. +