diff options
Diffstat (limited to 'docs/html/guide/appendix/api-levels.jd')
| -rw-r--r-- | docs/html/guide/appendix/api-levels.jd | 386 |
1 files changed, 321 insertions, 65 deletions
diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd index 8fc899bb4cc2..31581924c744 100644 --- a/docs/html/guide/appendix/api-levels.jd +++ b/docs/html/guide/appendix/api-levels.jd @@ -1,81 +1,337 @@ page.title=Android API Levels @jd:body +<div id="qv-wrapper"> +<div id="qv"> -<p>The Android <em>API Level</em> is an integer that indicates a set of APIs available in an Android SDK -and on a version of the Android platform. Each version of the Android platform supports a specific set -of APIs, which are always backward-compatible. For example, Android 1.5 supports all APIs available in -Android 1.0, but the reverse is not true. If an application uses APIs -available in Android 1.5 that are not available in 1.0, then the application should never be installed -on an Android 1.0 device, because it will fail due to missing APIs. The API Level ensures this does not happen -by comparing the minimum API Level required by the applicaiton to the API Level available on the device.</p> - -<p>When a new version of Android adds APIs, a new API Level is added to the platform. The new APIs -are available only to applications that declare a minimum API Level that is equal-to or greater-than -the API Level in which the APIs were introduced. The API Level required by an application is declared with the -<code><uses-sdk></code> element inside the Android manifest, like this:</p> - -<pre><uses-sdk android:minSdkVersion="3" /></pre> - -<p>The value for <code>minSdkVersion</code> is the minimum API Level required by the application. -If this is not declared, then it is assumed that the application is compatible with all versions and defaults to -API Level 1. In which case, if the application actually uses APIs introduced with an API Level greater than 1, then -the application will fail in unpredictable ways when installed on a device that only supports API Level 1 -(such as an Android 1.0 device). -See the <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> -documentation for more about declaring the API Level in your manifest.</p> - -<p>For example, the {@link android.appwidget} package was introduced with API Level 3. If your application -has set <code>minSdkVersion</code> to 1 or 2, then your application cannot use this package, -even if the device running your application uses a version of Android that supports it. -In order to use the {@link android.appwidget} package, your application must set <code>minSdkVersion</code> -to 3 or higher. When the <code>minSdkVersion</code> is set to 3, the application will no longer be able to install -on a device running a platform version with an API Level less than 3.</p> - -<p>Despite the name of the manifest attribute (<code>minSdkVersion</code>), the API Level is not directly -associated with a specific SDK. For example, the SDK for Android 1.0 uses -API Level 1 and the SDK for Android 1.1 uses API Level 2. So it may seem that the API Level increases consistently. -However, it's possible that a subsequent platform -releases will not introduce new APIs, and thus, the API Level will remain the same. In addition, there are often -multiple SDK releases for a single platform version (there were three SDK releases for Android 1.5), and -there's no guarantee that the API Level will remain the same between these. It's possible (but unlikely) that -a second or third SDK for a given version of the platform will provide new APIs and add a new API Level. -When you install a new SDK, be sure to read the SDK Contents on the install page, which specifies the API -Level for each platform available in the SDK. Also see the comparison of -<a href="#VersionsVsApiLevels">Platform Versions vs. API Levels</a>, below.</p> - -<p class="note"><strong>Note:</strong> During an "Early Look" SDK release, the APIs may not be final, so the -API Level number cannot be specified. In this case, a string value matching the -platform codename must be used as the value for <code>minSdkVersion</code>. This codename value -will only be valid while using the Early Look SDK with the emulator. An application using this API Level -can never be installed on an Android device. When the final SDK is released, you must update your manifest to use -the official API Level integer.</p> - -<h2 id="VersionsVsApiLevels">Platform Versions vs. API Levels</h2> - -<p>The following table specifies the <em>maximum</em> API Level supported by each version of the Android platform. -(Every platform is backward-compatible to API Level 1.)</p> + <h2>In this document</h2> +<ol> + <li><a href="intro">What is API Level?</a></li> + <li><a href="#uses">Uses of API Level in Android</a></li> + <li><a href="#considerations">Development Considerations</a> + <ol> + <li><a href="#fc">Application forward compatibility</a></li> + <li><a href="#bc">Application backward compatibility</a></li> + <li><a href="#platform">Selecting a platform version and API Level</a></li> + <li><a href="#apilevel">Declaring a minimum API Level</a></li> + <li><a href="#testing">Testing against higher API Levels</a></li> + </ol> + </li> + <li><a href="#provisional">Using a Provisional API Level</a></li> + <li><a href="#filtering">Filtering the Reference Documentation by API Level</a></li> +</ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> manifest element</li> + </ol> + +</div> +</div> + +<p>As you develop your application on Android, it's useful to understand the +platform's general approach to API change management. It's also important to +understand the API Level identifier and the role it plays in ensuring your +application's compatibility with devices on which it may be installed. </p> + +<p>The sections below provide information about API Level and how it affects +your applications. </p> + +<p>For information about how to use the "Filter by API Level" control +available in the API reference documentation, see +<a href="#filtering">Filtering the documentation</a> at the +end of this document. </p> + +<h2 id="intro">What is API Level?</h2> + +<p>API Level is an integer value that uniquely identifies the framework API +revision offered by a version of the Android platform.</p> + +<p>The Android platform provides a framework API that applications can use to +interact with the underlying Android system. The framework API consists of:</p> + +<ul> +<li>A core set of packages and classes</li> +<li>A set of XML elements and attributes for declaring a manifest file</li> +<li>A set of XML elements and attributes for declaring and accessing resources</li> +<li>A set of Intents</li> +<li>A set of permissions that applications can request, as well as permission +enforcements included in the system</li> +</ul> + +<p>Each successive version of the Android platform can include updates to the +Android application framework API that it delivers. </p> + +<p>Updates to the framework API are designed so that the new API remains +compatible with earlier versions of the API. That is, most changes in the API +are additive and introduce new or replacement functionality. As parts of the API +are upgraded, the older replaced parts are deprecated but are not removed, so +that existing applications can still use them. In a very small number of cases, +parts of the API may be modified or removed, although typically such changes are +only needed to ensure API robustness and application or system security. All +other API parts from earlier revisions are carried forward without +modification.</p> + +<p>The framework API that an Android platform delivers is specified using an +integer identifier called "API Level". Each Android platform version supports +exactly one API Level, although support is implicit for all earlier API Levels +(down to API Level 1). The initial release of the Android platform provided +API Level 1 and subsequent releases have incremented the API Level.</p> + +<p>The following table specifies the API Level supported by each version of the +Android platform.</p> <table> <tr><th>Platform Version</th><th>API Level</th></tr> - <tr><td>Android 1.0</td><td>1</td></tr> - <tr><td>Android 1.1</td><td>2</td></tr> + <tr><td>Android 1.6</td><td>4</td></tr> <tr><td>Android 1.5</td><td>3</td></tr> - <tr><td>Android Donut</td><td>Donut</td></tr> + <tr><td>Android 1.1</td><td>2</td></tr> + <tr><td>Android 1.0</td><td>1</td></tr> </table> -<h2 id="ViewingTheApiReference">Viewing the API Reference Based on API Level</h2> +<h2 id="uses">Uses of API Level in Android</h2> + +<p>The API Level identifier serves a key role in ensuring the best possible +experience for users and application developers: + +<ul> +<li>It lets the Android platform describe the maximum framework API revision +that it supports</li> +<li>It lets applications describe the framework API revision that they +require</li> +<li>It lets the system negotiate the installation of applications on the user's +device, such that version-incompatible applications are not installed.</li> +</ul> + +<p>Each Android platform version stores its API Level identifier internally, in +the Android system itself. </p> + +<p>Applications can use a manifest element provided by the framework API — +<code><uses-sdk></code> — to describe the minimum and maximum API +Levels under which they are able to run, as well as the preferred API Level that +they are designed to support. The element offers two key attributes:</p> + +<ul> +<li><code>android:minSdkVersion</code> — Specifies the minimum API Level +on which the application is able to run. The default value is "1".</li> +<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level +on which the application is able to run.</li> +</ul> + +<p>For example, to specify the minimum system API Level that an application +requires in order to run, the application would include in its manifest a +<code><uses-sdk></code> element with a <code>android:minSdkVersion</code> +attribute. The value of <code>android:minSdkVersion</code> would be the integer +corresponding to the API Level of the earliest version of the Android platform +under which the application can run. </p> + +<p>When the user attempts to install an application, the Android system first +checks the <code><uses-sdk></code> attributes in the application's +manifest and compares them against its own internal API Level. The system +allows the installation to begin only if these conditions are met:</p> + +<ul> +<li>If a <code>android:minSdkVersion</code> attribute is declared, its value +must be less than or equal to the system's API Level integer. If not declared, +the system assumes that the application requires API Level 1. </li> +<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value +must be equal to or greater than the system's API Level integer. +If not declared, the system assumes that the application +has no maximum API Level. </li> +</ul> + +<p>When declared in an application's manifest, a <code><uses-sdk></code> +element might look like this: </p> + +<pre><manifest> + ... + <uses-sdk android:minSdkVersion="4" /> + ... +</manifest></pre> + +<p>The principal reason that an application would declare an API Level in +<code>android:minSdkVersion</code> is to tell the Android system that it is +using APIs that were <em>introduced</em> in the API Level specified. If the +application were to be somehow installed on a platform with a lower API Level, +then it would crash at run-time when it tried to access APIs that don't exist. +The system prevents such an outcome by not allowing the application to be +installed if the lowest API Level it requires is higher than that of the +platform version on the target device.</p> + +<p>For example, the {@link android.appwidget} package was introduced with API +Level 3. If an application uses that API, it must declare a +<code>android:minSdkVersion</code> attribute with a value of "3". The +application will then be installable on platforms such as Android 1.5 (API Level +3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and +Android 1.0 platforms (API Level 1).</p> + +<p>For more information about how to specify an application's API Level +requirements, see the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> + section of the manifest file documentation.</p> + + +<h2 id="considerations">Development Considerations</h2> + +<p>The sections below provide information related to API level that you should +consider when developing your application.</p> + +<h3 id="fc">Application forward compatibility</h3> + +<p>Android applications are generally forward-compatible with new versions of +the Android platform.</p> + +<p>Because almost all changes to the framework API are additive, an Android +application developed using any given version of the API (as specified by its +API Level) is forward-compatible with later versions of the Android platform and +higher API levels. The application should be able to run on all later versions +of the Android platform, except in isolated cases where the application uses a +part of the API that is later removed for some reason. </p> + +<p>Forward compatibility is important because many Android-powered devices +receive over-the-air (OTA) system updates. The user may install your +application and use it successfully, then later receive an OTA update to a new +version of the Android platform. Once the update is installed, your application +will run in a new run-time version of the environment, but one that has the API +and system capabilities that your application depends on. </p> + +<p>In some cases, changes <em>below</em> the API, such those in the underlying +system itself, may affect your application when it is run in the new +environment. For that reason it's important for you, as the application +developer, to understand how the application will look and behave in each system +environment. To help you test your application on various versions of the Android +platform, the Android SDK includes multiple platforms that you can download. +Each platform includes a compatible system image that you can run in an AVD, to +test your application. </p> + +<h3 id="bc">Application backward compatibility</h3> + +<p>Android applications are not necessarily backward compatible with versions of +the Android platform older than the version against which they were compiled. +</p> + +<p>Each new version of the Android platform can include new framework APIs, such +as those that give applications access to new platform capabilities or replace +existing API parts. The new APIs are accessible to applications when running on +the new platform and, as mentioned above, also when running on later versions of +the platform, as specified by API Level. Conversely, because earlier versions of +the platform do not include the new APIs, applications that use the new APIs are +unable to run on those platforms.</p> + +<p>Although it's unlikely that an Android-powered device would be downgraded to +a previous version of the platform, it's important to realize that there are +likely to be many devices in the field that run earlier versions of the +platform. Even among devices that receive OTA updates, some might lag and +might not receive an update for a significant amount of time. </p> + +<h3 id="platform">Selecting a platform version and API Level</h3> + +<p>When you are developing your application, you will need to choose +the platform version against which you will compile the application. In +general, you should compile your application against the lowest possible +version of the platform that your application can support. + +<p>You can determine the lowest possible platform version by compiling the +application against successively lower build targets. After you determine the +lowest version, you should create an AVD using the corresponding platform +version (and API Level) and fully test your application. Make sure to declare a +<code>android:minSdkVersion</code> attribute in the application's manifest and +set its value to the API Level of the platform version. </p> + +<h3 id="apilevel">Declaring a minimum API Level</h3> + +<p>If you build an application that uses APIs or system features introduced in +the latest platform version, you should set the +<code>android:minSdkVersion</code> attribute to the API Level of the latest +platform version. This ensures that users will only be able to install your +application if their devices are running a compatible version of the Android +platform. In turn, this ensures that your application can function properly on +their devices. </p> + +<p>If your application uses APIs introduced in the latest platform version but +does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then +it will run properly on devices running the latest version of the platform, but +<em>not</em> on devices running earlier versions of the platform. In the latter +case, the application will crash at runtime when it tries to use APIs that don't +exist on the earlier versions.</p> + +<h3 id="testing">Testing against higher API Levels</h3> + +<p>After compiling your application, you should make sure to test it on the +platform specified in the application's <code>android:minSdkVersion</code> +attribute. To do so, create an AVD that uses the platform version required by +your application. Additionally, to ensure forward-compatibility, you should run +and test the application on all platforms that use a higher API Level than that +used by your application. </p> + +<p>The Android SDK includes multiple platform versions that you can use, +including the latest version, and provides an updater tool that you can use to +download other platform versions as necessary. </p> + +<p>To access the updater, use the <code>android</code> command-line tool, +located in the <sdk>/tools directory. You can launch the Updater by using +the <code>android</code> command without specifying any options. You can +also simply double-click the android.bat (Windows) or android (OS X/Linux) file. +In ADT, you can also access the updater by selecting +<strong>Window</strong> > <strong>Android SDK and AVD +Manager</strong>.</p> + +<p>To run your application against different platform versions in the emulator, +create an AVD for each platform version that you want to test. For more +information about AVDs, see <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. If +you are using a physical device for testing, ensure that you know the API Level +of the Android platform it runs. See the table at the top of this document for +a list of platform versions and their API Levels. </p> + + +<h2 id="provisional">Using a Provisional API Level</h2> + +<p>During an "Early Look" SDK release, the APIs may not be final, so the API Level integer +will not be specified. You must instead use a provisional API Level in your application +manifest in order to build applications against the Early Look platform. In this case, +the provisional API Level is not an integer, but a string matching the codename of the +unreleased platform version (for example, "Eclair"). The provisional API Level will be specified +in the Early Look SDK release notes and is case-sensitive.</p> + +<p>The use of a provisional API Level is designed to protect developers +and device users from inadvertently publishing or installing applications based on the +Early Look framework API, which may not run properly on actual devices running the final +system image.</p> + +<p>The provisional API Level will only be valid while using the Early Look SDK to run +applications in the emulator. An application using the provisional API Level can never be +installed on an Android device. When the final SDK is released, you must replace any +instances of the provisional API Level in your application manifest with the final +API Level integer.</p> + + +<h2 id="filtering">Filtering the Reference Documentation by API Level</h2> -<p>The Android API reference includes information that specififies the minimum API Level required for each -package, class, and member. You can see this information on the right side of each header or label.</p> +<p>Reference documentation pages on the Android Developers site offer a "Filter +by API Level" control in the top-right area of each page. You can use the +control to show documentation only for parts of the API that are actually +accessible to your application, based on the API Level that it specifies in +the <code>android:minSdkVersion</code> attribute of its manifest file. </p> -<p>By default, the reference documentation shows all APIs available with the latest SDK release. -This means that the reference assumes you're using the latest API Level and will show you everything available -with it. If you're developing applications for a version of Android that does not support the latest API Level, -then you can filter the reference to reveal only the packages, classes, and members available for that API Level. -When viewing the reference, use the "Filter by API Level" selection box (below the search box) to pick the API Level -you'd like to view.</p> +<p>To use filtering, set the control to the same API Level as that specified +by your application. Notice that APIs introduced in a later API Level are +then grayed out and their content is masked, since they would not be +accessible to your application. </p> +<p>Filtering by API Level in the documentation does not provide a view +of what is new or introduced in each API Level — it simply provides a way +to view the entire API associated with a given API Level, while excluding API +elements introduced in later API Levels.</p> +<p>By default, API Level filtering is enabled and set to show the latest API +Level. If you do not want to use filtering reference documentation, +simply select the highest available API Level. </p> +<p>Also note that the reference documentation for individual API elements +specifies the API Level at which the elements were introduced. The API Level +for packages and classes is specified as "Since <api level>" at the +top-right corner of the content area on each documentation page. The API Level +for class members is specified in their detailed description headers, +at the right margin. </p> |