From f278dab83eba9891ae1017e8bcd0ae4fddd44912 Mon Sep 17 00:00:00 2001
From: Joe Fernandez <joefernandez@google.com>
Date: Sun, 6 Mar 2016 19:14:25 -0800
Subject: [PATCH] docs: N Preview 1 - Behavior Changes

b/27498028

Change-Id: Icb5daafa950359849c8c07548ee4f6e1eb71ca0d
---
 docs/html/preview/behavior-changes.jd | 455 +++++++++++++++++++++++++-
 1 file changed, 451 insertions(+), 4 deletions(-)

diff --git a/docs/html/preview/behavior-changes.jd b/docs/html/preview/behavior-changes.jd
index 52c108912ab8f..643fe551d5ed9 100644
--- a/docs/html/preview/behavior-changes.jd
+++ b/docs/html/preview/behavior-changes.jd
@@ -5,8 +5,455 @@ page.tags="preview", "developer preview"
 page.image=images/cards/card-n-changes_2x.png
 @jd:body
 
+
+<div id="qv-wrapper">
+<div id="qv">
+
+<h2>In this document</h2>
+
+<ol id="toc44" class="hide-nested">
+  <li><a href="#behavior-power">Battery Performance</a>
+    <ol>
+      <li><a href="#doze">Doze</a></li>
+      <li><a href="#bg-opt">Background Optimizations</a></li>
+    </ol>
+  </li>
+  <li><a href="#">Permissions Changes</a></li>
+  <li><a href="#behavior-power">Accessibility Improvements</a>
+    <ol>
+      <li><a href="#doze">Screen Zoom</a></li>
+      <li><a href="#bg-opt">Vision Settings in Setup Wizard</a></li>
+    </ol>
+  </li>
+  <li><a href="#">Platform Migration toward OpenJDK 8</a></li>
+  <li><a href="#">NDK Apps Linking to Platform Libraries</a></li>
+</ol>
+
+<h2>See Also</h2>
+<ol>
+  <li><a href="{@docRoot}preview/api-overview.html">
+    M Developer Preview API Overview</a></li>
+</ol>
+
+</div>
+</div>
+
+
 <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.
-</p>
\ No newline at end of file
+  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="batt-perf">Battery Performance</h2>
+
+<p>
+  The Preview contains system behavior changes aimed at improving the battery
+  life of devices. 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="" alt="" height="XXX" 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. After some more time
+  elapses, 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="" alt="" height="XXX" id="figure1" />
+<p class="img-caption">
+  <strong>Figure 1.</strong> Illustration of how Doze applies a second level of
+  system activity restrictions to further improve battery life.
+</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). You should still
+  follow those recommendations, such as using Google Cloud Messaging (GCM) to
+  send and receive messages, and start planning updates for the additional Doze
+  behavior.
+</p>
+
+
+<h3 id="bg-opt">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.
+  </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="">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 Improvements</h2>
+
+<p>
+  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</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>
+
+
+<img src="{@docRoot}images/image-0.png" alt="" height="XXX" id="figure1" />
+<p class="img-caption">
+  <strong>Figure 1.</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 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="">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>
+
+
+<h2 id="">NDK Apps Linking to Platform Libraries</h2>
+
+<p>
+  In the Preview, an application built with the NDK and targeting the N Preview
+  API cannot link against the platform libraries shipped with the NDK. This
+  change affects both the dlopen(3) and DT_NEEDED entries in your {@code .so}
+  files.
+</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>
+  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 -&gt; GetJavaVM from &lt;jni.h&gt;
+AndroidRuntime::getJNIEnv -&gt; JavaVM::GetEnv or
+JavaVM::AttachCurrentThread from &lt;jni.h&gt;.
+</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 &lt;sys/system_properties.h&gt; 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>