Merge changes from topic 'n-changes' into mnc-mr-docs

page.image=images/cards/card-n-changes_2x.png

@jd:body

<div id="qv-wrapper">

<div id="qv">

<h2>In this document</h2>

<ol>

  <li><a href="#perf">Performance Improvements</a>

    <ol>

      <li><a href="#doze">Doze</a></li>

      <li><a href="#bg-opt">Background Optimizations</a></li>

    </ol>

  </li>

  <li><a href="#perm">Permissions Changes</a></li>

  <li><a href="#accessibility">Accessibility Improvements</a>

    <ol>

      <li><a href="#screen-zoom">Screen Zoom</a></li>

      <li><a href="#vision-settings">Vision Settings in Setup Wizard</a></li>

    </ol>

  </li>

  <li><a href="#open-jdk">Platform Migration toward OpenJDK 8</a></li>

  <li><a href="#ndk">NDK Apps Linking to Platform Libraries</a></li>

  <li><a href="#afw">Android for Work</a></li>

</ol>

<h2>See Also</h2>

<ol>

  <li><a href="{@docRoot}preview/api-overview.html">

    N Developer Preview API Overview</a></li>

</ol>

</div>

</div>

<p>

  Along with new features and capabilities, the Android N Developer Preview

  includes a variety of system and API behavior changes. This document

  highlights some of the key changes that you should understand and account for

  in your apps.

</p>

<p>

  If you have previously published an app for Android, be aware that your app

  might be affected by these changes in the platform.

</p>

<h2 id="perf">Performance Improvements</h2>

<p>

  The Preview contains system behavior changes aimed at improving the battery

  life of devices, RAM usage, and app performance. These changes can impact the

  availability of system resources and system notifications to your app. You

  should review these changes and evaluate how your app may need to adjust to

  them.

</p>

<h3 id="doze">Doze</h3>

<p>

  Introduced in Android 6.0 (API level 23), Doze improves battery life by

  deferring CPU and network activities when a user leaves a device unplugged,

  stationary, and with the screen turned off. This Preview brings further

  enhancements to Doze by applying a subset of CPU and network restrictions

  while the device is unplugged with the screen turned off, but not necessarily

  stationary, for example, when a handset is traveling in a user’s pocket.

</p>

<img src="{@docRoot}preview/images/doze-diagram-1.png"

  alt="" height="251px" id="figure1" />

<p class="img-caption">

  <strong>Figure 1.</strong> Illustration of how Doze applies a first level of

  system activity restrictions to improve battery life.

</p>

<p>

  When a device is on battery power, and the screen has been off for a certain

  time, the device enters Doze and applies the first subset of restrictions: It

  shuts off app network access, and defers jobs and syncs. If the device is

  stationary for a certain time after entering Doze, the system applies the

  rest of the Doze restrictions to {@link android.os.PowerManager.WakeLock},

  {@link android.app.AlarmManager} alarms, GPS, and Wi-Fi scans.. Regardless of

  whether some or all Doze restrictions are being applied, the system wakes the

  device for brief maintenance windows, during which applications are allowed

  network access and can execute any deferred jobs/syncs.

</p>

<img src="{@docRoot}preview/images/doze-diagram-2.png"

  alt="" id="figure2" />

<p class="img-caption">

  <strong>Figure 2.</strong> Illustration of how Doze applies a second level of

  system activity restrictions after the device is stationary for a certain time.

</p>

<p>

  Note that activating the screen on or plugging in the device exits Doze and

  removes these processing restrictions. The additional behavior does not

  affect recommendations and best practices in adapting your app to the prior

  version of Doze introduced in Android 6.0 (API level 23), as discussed in

  <a href=”{@docRoot}/training/monitoring-device-state/doze-standby.html”>

  Optimizing for Doze and App Standby</a>. You should still

  follow those recommendations, such as using Google Cloud Messaging (GCM) to

  send and receive messages, and start planning updates to accomodate the

  additional Doze behavior.

</p>

<h3 id="bg-opt">Project Svelte: Background Optimizations</h3>

<p>

  The Preview removes three implicit broadcasts in order to help optimize both

  memory use and power consumption. This change is necessary because implicit

  broadcasts frequently start apps that have registered to listen for them in

  the background. Removing these broadcasts can substantially benefit device

  performance and user experience.

</p>

<p>

  Mobile devices experience frequent connectivity changes, such as when moving

  between Wi-Fi and mobile data. Currently, apps can monitor for changes in

  connectivity by registering a receiver for the implicit {@link

  android.net.ConnectivityManager#CONNECTIVITY_ACTION} broadcast in their

  manifest. Since many apps register to receive this broadcast, a single

  network switch can cause them all to wake up and process the broadcast at

  once.

</p>

<p>

  Similarly, apps can register to receive implicit {@code NEW_PICTURE} and

  {@code NEW_VIDEO} broadcasts from other apps, such as Camera. When a user

  takes a picture with the Camera app, these apps wake up to process the

  broadcast.

</p>

<p>

  To alleviate these issues, the Preview applies the following

  optimizations:

</p>

<ul>

  <li>Apps targeting the Preview do not receive {@link

  android.net.ConnectivityManager#CONNECTIVITY_ACTION} broadcasts, even if they

  have manifest entries to request notification of these events. Apps running

  in the foreground can still listen for {@code CONNECTIVITY_CHANGE} on their

  main thread if they request notification with a

  {@link android.content.BroadcastReceiver}.

  </li>

  <li>Apps cannot send or receive {@code NEW_PICTURE} or {@code NEW_VIDEO}

  broadcasts. This optimization affects all apps, not only those

  targeting the Preview.

  </li>

</ul>

<p>

  Future releases of Android may deprecate additional implicit broadcasts, as

  well as unbound background services. For this reason, you should avoid or

  remove dependencies on manifest-declared receivers for implicit broadcasts,

  as well as on background services.

</p>

<p>

  The Android framework provides several solutions to mitigate the need for

  these implicit broadcasts or background services. For example, the {@link

  android.app.job.JobScheduler} API provides a robust mechanism to schedule

  network operations when specified conditions, such as connection to an

  unmetered network, are met. You can even use {@link

  android.app.job.JobScheduler} to react to changes to content providers.

</p>

<p>

  For more information about this behavior change and how to adapt your app,

  see <a href=

  "{@docRoot}preview/features/background-optimization.html">Background

  Optimizations</a>.

</p>

<h2 id="perm">Permissions Changes</h2>

<p>

  The Preview includes changes to permissions that may affect your app,

  including user accounts permissions and a new permission for writing to

  external storage. Here is a summary of the permissions that have changed in

  the preview:

</p>

<ul>

  <li>{@code GET_ACCOUNTS} (Deprecated)

    <p>

      The GET_ACCOUNTS permission is now deprecated. The system ignores this

      permission for apps that target the N Developer Preview.

    </p>

  </li>

  <li>{@code ACTION_OPEN_EXTERNAL_DIRECTORY} (New)

    <p>

      This permission is for a new storage option. Apps can now use the intent

      {@code ACTION_OPEN_EXTERNAL_DIRECTORY} to request that the system create a

      directory for the app's use. The system prompts the user to grant

      approval. If the user approves, the app can read and write files and

      directories in that one directory (and its descendants). The app does not

      need {@link android.Manifest.permission_group#STORAGE STORAGE}

      permissions to access this external directory

    </p>

    <p>

      For more information about this intent, see the updated

      {@code Intent} reference documentation in the

      <a href="{@docRoot}preview/download.html#docs">N Preview SDK Reference</a>.

    </p>

  </li>

</ul>

<h2 id="accessibility">Accessibility Improvements</h2>

<p>

This page is under construction. For now,

<a href="https://docs.google.com/document/d/1TA8Vzoa7KQ99bj1GVD81ps3Ux4wY0Ctkz7dC7bNnslU/edit">this

doc</a> contains information on upcoming behavior changes.

  This Preview includes changes intended to improve the usability of the

  platform for users with low or impaired vision. These changes should

  generally not require code changes in your app, however you should review

  these feature and test them with your app to assess potential impacts to user

  experience.

</p>

<h3 id="screen-zoom">Screen Zoom</h3>

<p>

  The Preview enables users to set <strong>Display size</strong>which magnifies

  or shrinks all elements on the screen, thereby improving device accessibility

  for users with low vision. Users cannot zoom the screen past a minimum screen

  width of <a href=

  "http://developer.android.com/guide/topics/resources/providing-resources.html">

  sw320dp</a>, which is the width of a Nexus 4, a common medium-sized phone.

</p>

<div class="cols">

<div class="col-6">

  <img src="{@docRoot}preview/images/screen-zoom-1.png" alt="" height="XXX" id="figure1" />

</div>

<div class="col-6">

  <img src="{@docRoot}preview/images/screen-zoom-2.png" alt="" height="XXX" id="figure1" />

</div>

</div> <!-- end cols -->

<p class="img-caption">

  <strong>Figure 3.</strong> The screen on the right shows the effect of

  increasing the Display size of a device running an N Preview system image.

</p>

<p>

  When the device density changes, the system notifies running apps in the

  following ways:

</p>

<ul>

  <li>If an app targets API level 23 or lower, the system automatically kills

  all its background processes. This means that if a user switches away from

  such an app to open the <em>Settings</em> screen and changes the

  <strong>Display size</strong> setting, the system kills the app in the same

  manner that it would in a low-memory situation. If the app has any foreground

  processes, the system notifies those processes of the configuration change as

  described in <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling

  Runtime Changes</a>, just as if the device's orientation had changed.

  </li>

  <li>If an app targets the N Developer Preview, all of its processes

  (foreground and background) are notified of the configuration change as

  described in <a href=

  "{@docRoot}guide/topics/resources/runtime-changes.html">Handling

  Runtime Changes</a>.

  </li>

</ul>

<p>

  Most apps do not need to make any changes to support this feature, provided

  the apps follow Android best practices. You should verify that your app

  behaves properly under Screen Zoom.

</p>

<h3 id="vision-settings">Vision Settings in Setup Wizard</h3>

<p>

  The Preview includes Vision Settings on the Welcome screen, where users can

  set up the following accessibility settings on a new device:

  <strong>Magnification gesture</strong>, <strong>Font size</strong>,

  <strong>Display size</strong> and <strong>TalkBack</strong>. This change

  increases the visibility of bugs related to different screen settings. To

  assess the impact of this feature, you should test your apps with these

  settings enabled. You can find the settings under <strong>Settings &gt;

  Accessibility</strong>.

</p>

<h2 id="open-jdk">Platform Migration toward OpenJDK 8</h2>

<p>

  The Preview moves Android’s Java language libraries to an OpenJDK-based

  approach, creating a common code base for developers to build apps and

  services. If your app depends on a private implementation of Java or

  unspecified behavior, you should be aware of these known issues:

</p>

<ul>

  <li>The {@code ArrayList} private field array is removed.

    <p>

      If your app, or a library it used, was dependent on a private field of

      the ArrayList class, you may encounter an exception such as:

    </p>

<pre>

java.lang.NoSuchFieldException: No field array in class Ljava/util/ArrayList;

</pre>

  </li>

  <li>Calling a {@code Comparator} implementation with equal elements is

  possible.

    <p>

      You can now call implementations of Comparator to compare an element to

      itself. However, doing so may cause problems if the Comparator expects to

      be called only with unique arguments.

    </p>

  </li>

  <li>Crypto security provider has been removed.

    <p>

      You should only call to the Java Cryptography Extension (JCE) APIs with a

      provider listed if the provider is included in the code of the APK.

      Otherwise, your app needs to be able to handle the provider’s absence.

    </p>

    <p>

      The reason apps use this provider is to take advantage of its

      SecureRandom implementation. If your app was relying on setSeed() to

      derive keys from strings, you must either switch to using SecretKeySpec

      to load raw key bytes directly, or use a real key derivation function

      (KDF).

    </p>

  </li>

</ul>

<h2 id="ndk">NDK Apps Linking to Platform Libraries</h2>

<p>

  The Preview includes namespace changes to prevent loading of non-public APIs.

  If you use the NDK, you should only be using public APIs from the Android

  platform. Using non-public APIs in the next official release of Android

  can cause your app to crash.

</p>

<p>

  In order to alert you to use of non-public APIs, apps running on a Preview

  device generate an error in logcat output when an app calls a non-public API.

  This error is also displayed on the device screen as a message to help

  raise awareness of this situation. You should review your app code to

  remove use of non-public platform APIs and thoroughly test your apps using

  a preview device or emulator.

</p>

<p>

  If your app depends on platform libraries, see the NDK documentation for

  typical fixes for replacing common private APIs with public API equivalents.

  You may also be linking to platform libraries without realizing it,

  especially if your app uses a library that is part of the platform (such as

  <code>libpng</code>), but is not part of the NDK. In that case, ensure that

  your APK contains all the .so files you intended to link against.

</p>

<p class="caution">

  <strong>Caution:</strong> Some third-party libraries may link to non-public

  APIs. If your app uses these libraries, your app may crash when running

  on the next official release of Android.

</p>

<p>

  Apps should not depend on or use native libraries that are not included in

  the NDK, because they may change, or be removed from one Android release to

  another. The switch from OpenSSL to BoringSSL is an example of such a change.

  Also, different devices may offer different levels of compatibility, because

  there are no compatibility requirements for platform libraries not included

  in the NDK. If you must access non-NDK libraries on older devices, make the

  loading dependent on the Android API level.

</p>

<p>

  To help you diagnose these types problems here are some example Java and NDK

  errors you might encounter when attempting to build your app with the N

  Developer Preview:

</p>

<p>Example Java error:</p>

<pre>

java.lang.UnsatisfiedLinkError: dlopen failed: library "/system/lib/libcutils.so"

    is not accessible for the namespace "classloader-namespace"

</pre>

<p>Example NDK error:</p>

<pre>

dlopen failed: cannot locate symbol "__system_property_get" referenced by ...

</pre>

<p>

  Here are some typical fixes for apps encountering these types of errors:

</p>

<ul>

  <li>Use of getJavaVM and getJNIEnv from libandroid_runtime.so can be replaced

  with standard JNI functions:

<pre>

AndroidRuntime::getJavaVM -> GetJavaVM from <jni.h>

AndroidRuntime::getJNIEnv -> JavaVM::GetEnv or

JavaVM::AttachCurrentThread from <jni.h>.

</pre>

  </li>

  <li>Use of {@code property_get} symbol from {@code libcutils.so} can be

    replaced with the public {@code alternative __system_property_get}:

<pre>

#include <sys/system_properties.h> and use __system_property_get

</pre>

  </li>

  <li>Use of {@code SSL_ctrl} symbol from {@code libcrypto.so} should be

  replaced with an app local version. For example, you should statically link

  {@code libcyrpto.a} in your {@code .so} file or include your own dynamically

  {@code libcrypto.so} from BoringSSL or OpenSSL in your app.

  </li>

</ul>

<h2 id="afw">Android for Work</h2>

<p>

  The Preview contains changes for apps that target Android for Work, including

  changes to certificate installation, password resetting, secondary user

  management, and access to device identifiers. If you are building apps for

  Android for Work environments, you should review these changes and modify

  your app accordingly.

</p>

<ul>

  <li>You must install a delegated certificate installer before the DPC can set

  it. For both profile and device-owner apps targeting the N SDK, you should

  install the delegated certificate installer before the device policy

  controller (DPC) calls

  <code>DevicePolicyManager.setCertInstallerPackage()</code>. If the installer

  is not already installed, the system throws an

  <code>IllegalArgumentException</code>.

  </li>

  <li>Reset password restrictions for device admins now apply to profile

  owners.Device admins can no longer use

  <code>DevicePolicyManager.resetPassword()</code>to clear passwords or change

  ones that are already set. Device admins can still set a password, but only

  when the device has no password, PIN, or pattern.

  </li>

  <li>Device and profile owners can manage accounts even if restrictions are

  set.Device owners and profile owners can call the Account Management APIs

  even if <code>DISALLOW_MODIFY_ACCOUNTS</code> user restrictions are in place.

  </li>

  <li>Device owners can manage secondary users more easily.When a device is

  running in device owner mode, the <code>DISALLOW_ADD_USER</code> restriction

  is automatically set. This prevents users from creating unmanaged secondary

  users. In addition, the <code>CreateUser()</code> and

  <code>createAndInitial()</code> methods are deprecated; the new

  <code>DevicePolicyManager.createAndManageUser()</code> method replaces them.

  </li>

  <li>Device owners can access device identifiers.A Device owner can access the

  Wi-Fi MAC address of a device, using

  <code>DevicePolicyManagewr.getWifiMacAddress()</code> . If Wi-Fi has never

  been enabled on the device, this method returns a value of {@code null}.

  </li>

</ul>