Clarify docs for BackupTransport.initializeDevice()

Explicitly call out that even if the backend is in an undefined state
(such as no authenticated account, so there is by definition no work
that can be done here), the transport should return TRANSPORT_OK in
response to initializeDevice().  Error returns from that method must
only be used to indicate that the initialize should be *retried*.

Bug 21136957

Change-Id: I41ad115b92c16092b4d931d9c554a44b77945359

1 files changed, 10 insertions, 1 deletions

diff --git a/core/java/android/app/backup/BackupTransport.java b/core/java/android/app/backup/BackupTransport.java
index 9540eb1..4d2158f 100644
--- a/core/java/android/app/backup/BackupTransport.java
+++ b/core/java/android/app/backup/BackupTransport.java
@@ -162,8 +162,17 @@ public class BackupTransport {
      * this is called, {@link #finishBackup} will be called to ensure the request
      * is sent and received successfully.
      *
+     * <p>If the transport returns anything other than TRANSPORT_OK from this method,
+     * the OS will halt the current initialize operation and schedule a retry in the
+     * near future.  Even if the transport is in a state such that attempting to
+     * "initialize" the backend storage is meaningless -- for example, if there is
+     * no current live dataset at all, or there is no authenticated account under which
+     * to store the data remotely -- the transport should return TRANSPORT_OK here
+     * and treat the initializeDevice() / finishBackup() pair as a graceful no-op.
+     *
      * @return One of {@link BackupTransport#TRANSPORT_OK} (OK so far) or
-     *   {@link BackupTransport#TRANSPORT_ERROR} (on network error or other failure).
+     *   {@link BackupTransport#TRANSPORT_ERROR} (to retry following network error
+     *   or other failure).
      */
     public int initializeDevice() {
         return BackupTransport.TRANSPORT_ERROR;