From a6602f1fe4590e48c760f21ce29a92629240c463 Mon Sep 17 00:00:00 2001 From: Dirk Dougherty Date: Thu, 27 Aug 2009 16:26:43 -0700 Subject: Add docs for SDK update. Add redirects for preview files. Manually integrate a few doc changes from cupcake. Change-Id:I524d7dbf929371ee501599229894640660f352ce --- docs/html/guide/appendix/api-levels.jd | 372 +++++++++++++++++++++++++++------ 1 file changed, 307 insertions(+), 65 deletions(-) (limited to 'docs/html/guide/appendix/api-levels.jd') diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd index 8fc899b..a4dcc5e 100644 --- a/docs/html/guide/appendix/api-levels.jd +++ b/docs/html/guide/appendix/api-levels.jd @@ -1,81 +1,323 @@ page.title=Android API Levels @jd:body +
+
-

The Android API Level 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.

- -

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 -<uses-sdk> element inside the Android manifest, like this:

- -
<uses-sdk android:minSdkVersion="3" />
- -

The value for minSdkVersion 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 <uses-sdk> -documentation for more about declaring the API Level in your manifest.

- -

For example, the {@link android.appwidget} package was introduced with API Level 3. If your application -has set minSdkVersion 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 minSdkVersion -to 3 or higher. When the minSdkVersion 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.

- -

Despite the name of the manifest attribute (minSdkVersion), 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 -Platform Versions vs. API Levels, below.

- -

Note: 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 minSdkVersion. 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.

- -

Platform Versions vs. API Levels

- -

The following table specifies the maximum API Level supported by each version of the Android platform. -(Every platform is backward-compatible to API Level 1.)

+

In this document

+
    +
  1. What is API Level?
    2. +
  2. Uses of API Level
    3. +
  3. Development Considerations +
      +
    1. Application forward compatibility
      2. +
    2. Application backward compatibility
      3. +
    3. Selecting a platform version for compiling
      4. +
    4. Declaring a minimum API Level
      5. +
    5. Testing against higher API Levels
      6. +
    +
    4. +
  4. Filtering the documentation
    5. +
+ +

See also

+
    +
  1. <uses-sdk> manifest element
    2. +
+ +
+
+ +

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.

+ +

The sections below provide information about API Level and how it affects +your applications.

+ +

For information about how to use the "Filter by API Level" control +available in the API reference documentation, see +Filtering the documentation at the +end of this document.

+ +

What is API Level?

+ +

API Level is an integer value that uniquely identifies the framework API +revision offered by a version of the Android platform.

+ +

The Android platform provides a framework API that applications can use to +interact with the underlying Android system. The framework API consists of:

+ + + +

Each successive version of the Android platform can include updates to the +Android application framework API that it delivers.

+ +

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.

+ +

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.

+ +

The following table specifies the API Level supported by each version of the +Android platform.

- - + - + +
Platform VersionAPI Level
Android 1.01
Android 1.12
Android 1.64
Android 1.53
Android DonutDonut
Android 1.12
Android 1.01
-

Viewing the API Reference Based on API Level

+

Uses of API Level in Android

+ +

The API Level identifier serves a key role in ensuring the best possible +experience for users and application developers: + +

+ +

Each Android platform version stores its API Level identifier internally, in +the Android system itself.

+ +

Applications can use a manifest element provided by the framework API — +<uses-sdk> — 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:

+ + + +

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 +<uses-sdk> element with a android:minSdkVersion +attribute. The value of android:minSdkVersion would be the integer +corresponding to the API Level of the earliest version of the Android platform +under which the application can run.

+ +

When the user attempts to install an application, the Android system first +checks the <uses-sdk> 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:

+ + + +

When declared in an application's manifest, a <uses-sdk> +element might look like this:

+ +
<manifest>
+  ...
+  <uses-sdk android:minSdkVersion="4" />
+  ...
+</manifest>
+ +

The principal reason that an application would declare an API Level in +android:minSdkVersion is to tell the Android system that it is +using APIs that were introduced 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 tries 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.

+ +

For example, the {@link android.appwidget} package was introduced with API +Level 3. If an application uses that API, it must declare a +android:minSdkVersion 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).

+ +

For more information about how to specify an application's API Level +requirements, see the <uses-sdk> + section of the manifest file documentation.

+ + +

Development Considerations

+ +

The sections below provide information related to API level that you should +consider when developing your application.

+ +

Application forward compatibility

+ +

Android applications are generally forward-compatible with new versions of +the Android platform.

+ +

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.

+ +

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 it depends on.

+ +

In some cases, changes below 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.

+ +

Application backward compatibility

+ +

Android applications are not necessarily backward compatible with versions of +the Android platform older than the version against which they were compiled. +

+ +

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.

+ +

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 not +receive an update for a significant amount of time.

+ +

Selecting a platform version and API Level

+ +

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. + +

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 +android:minSdkVersion attribute in the application's manifest and +set its value to the API Level of the platform version.

+ +

Declaring a minimum API Level

+ +

If you build an application that uses APIs or system features introduced in +the latest platform version, you should set the +android:minSdkVersion 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.

+ +

If your application uses APIs introduced in the latest platform version but +does not declare a android:minSdkVersion attribute, then +it will run properly on devices running the latest version of the platform, but +not 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.

+ +

Testing against higher API Levels

+ +

After compiling your application, you should make sure to test it on the +platform specified in the application's android:minSdkVersion +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.

+ +

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.

+ +

To access the updater, use the android command-line tool, +located in the <sdk>/tools directory. You can launch the Updater by using +the android 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 +Window > Android SDK and AVD +Manager.

+ +

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 Android Virtual Devices. 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.

+ + + +

Filtering the Reference Documentation by API Level

+ +

Reference documentation pages on the Android Developers site offer a "Filter +by API Level" control in the top-right area of each page.

-

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.

+

The "Filter by API Level" lets you 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 minSdkVersion attribute in its manifest +file

-

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.

+

When you filter the reference documentation by an API level, only the APIs +available at that API level are shown. APIs introduced in a later API level are +grayed out and their content is masked, since they would not be accessible to +your application.

+

Note that filtering by API Level in the documentation does not provide a view +of what is new or introduced in each API Level. Filtering simply provides a way +to view the entire API associated with a given API Level, while excluding API +elements introduced in later API Levels.

+

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, select the +highest available API Level.

+

Note that the reference documentation for API elements also specifies the API +Level at which the element was 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 each class member is +specified in the member's detailed description section header, at the right +margin.

-- cgit v1.1