android_frameworks_base/docs/html/preview/features/icu4j-framework.jd

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>