docs: Added documentation for ICU4J Android Framework.
Bug:27076197 Change-Id: I123df56123cbe5e8b5ea16bdf4d7333475617199
This commit is contained in:
sreevanis
committed by
Andrew Solovay
Andrew Solovay
parent
e90d9993e9
commit
2a7120fe5d
175
docs/html/preview/features/icu4j-framework.jd
Normal file
175
docs/html/preview/features/icu4j-framework.jd
Normal file
@@ -0,0 +1,175 @@
|
||||
page.title=Using ICU4J Android Framework APIs
|
||||
|
||||
@jd:body
|
||||
|
||||
<div id="tb-wrapper">
|
||||
<div id="tb">
|
||||
<h2>In this document:</h2>
|
||||
<ol>
|
||||
<li><a href="#compatibility">Compatibility Across Android Releases</a></li>
|
||||
<li><a href="#relation">Relationship to ICU4J</a></li>
|
||||
<li><a href="#migration">Migrating to android.icu APIs from ICU4J </a></li>
|
||||
<li><a href="#licence">Licensing</a></li>
|
||||
</ol>
|
||||
|
||||
<h2>See Also</h2>
|
||||
<ol>
|
||||
<li>
|
||||
<a class="external-link" href=
|
||||
"http://userguide.icu-project.org">Documentation for ICU4J</a>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<a class="external-link" href=
|
||||
"http://site.icu-project.org/#TOC-What-is-ICU-">Latest standards supported
|
||||
by ICU4J</a>
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h2 id="compatibility">Compatibility Across Android Releases</h2>
|
||||
|
||||
<p>
|
||||
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 <a href=
|
||||
"{@docRoot}guide/practices/compatibility.html#Versions">Device
|
||||
Compatibility</a>.
|
||||
</p>
|
||||
|
||||
<h2 id="relation">Relationship to ICU4J</h2>
|
||||
|
||||
<p>
|
||||
The N Developer Preview provides a subset of the full ICU4J APIs under the
|
||||
<code>android.icu</code> 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.
|
||||
</p>
|
||||
|
||||
<p class="table-caption"><strong>Table 1.</strong> ICU and CLDR versions used in the N Developer Preview.
|
||||
<table>
|
||||
<tr>
|
||||
<th>Android API level</th>
|
||||
<th>ICU version</th>
|
||||
<th>CLDR version</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N Developer Preview</td>
|
||||
<td>56</td>
|
||||
<td>28</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p class="note">
|
||||
<b>Note</b>: 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
|
||||
<code>java.util</code> and <code>java.text</code> classes on Android. These
|
||||
differences are the result of improvements to translations between Android
|
||||
versions.
|
||||
</p>
|
||||
|
||||
<p>Here are a few important things to note:</p>
|
||||
|
||||
<ul>
|
||||
<li>The ICU4J Android Framework APIs do not include all the ICU4J APIs.</li>
|
||||
<li>Android does not expose the ICU4C APIs for developers using the NDK.</li>
|
||||
<li>The ICU4J Android Framework APIs do not replace Android’s support for
|
||||
<a href="{@docRoot}guide/topics/resources/localization.html">Localizing with
|
||||
Resources</a>.</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="migration">Migrating to android.icu APIs from ICU4J</h2>
|
||||
|
||||
<p>
|
||||
If you are already using ICU4J APIs in your app, and the
|
||||
<code>android.icu</code> APIs meet your requirements, then migrating to
|
||||
<code>android.icu</code> framework requires you to change your Java imports
|
||||
from <code>com.ibm.icu</code> to <code>android.icu.</code> You may then
|
||||
remove your own copy of ICU4J files from the APK.
|
||||
</p>
|
||||
|
||||
<p class="note">
|
||||
<b>Note</b>: The ICU4J Android Framework exposes the classes in the
|
||||
<code>android.icu</code>
|
||||
package instead of <code>com.ibm.icu</code>. This is to avoid conflicts with
|
||||
a copy of ICU4J that may be included in your app’s .apk file.
|
||||
</p>
|
||||
|
||||
<h3 id="migrate-from-android">
|
||||
Migrating to android.icu APIs from other Android SDK APIs
|
||||
</h3>
|
||||
|
||||
<p>
|
||||
Some classes in the <code>java</code> and<code>android</code> packages have
|
||||
equivalents to those found in ICU4J. The ICU4J version often provides more
|
||||
complete support for standards or a wider range of languages.
|
||||
</p>
|
||||
<p>Here are some examples to get you started:</p>
|
||||
<table>
|
||||
<tr>
|
||||
<th>Class</th>
|
||||
<th>Alternatives</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>java.lang.Character</code> </td>
|
||||
<td><code>android.icu.lang.UCharacter</code> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>java.text.BreakIterator</code> </td>
|
||||
<td><code>android.icu.text.BreakIterator</code> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>java.text.DecimalFormat</code> </td>
|
||||
<td><code>android.icu.text.DecimalFormat</code> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>java.util.Calendar</code></td>
|
||||
<td>
|
||||
<code>android.icu.util.Calendar</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>android.text.BidiFormatter</code>
|
||||
</td>
|
||||
<td><code>android.icu.text.Bidi</code>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>android.text.format.DateFormat</code>
|
||||
</td>
|
||||
<td><code>android.icu.text.DateFormat</code>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>android.text.format.DateUtils</code> </td>
|
||||
<td><code>android.icu.text.DateFormat</code>
|
||||
<code>android.icu.text.RelativeDateTimeFormatter</code>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2 id="licence">Licensing</h2>
|
||||
|
||||
<p>
|
||||
ICU4J is released under a nonrestrictive <a class="external-link" href=
|
||||
"http://source.icu-project.org/repos/icu/icu/trunk/license.html">open source
|
||||
license</a>.
|
||||
</p>
|
||||
Reference in New Issue
Block a user