Home | History | Annotate | Download | only in content
      1 /*
      2  * Copyright (C) 2008 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.content;
     18 
     19 import android.os.Parcel;
     20 import android.os.Parcelable;
     21 
     22 /**
     23  * This class is used to communicate the results of a sync operation to the SyncManager.
     24  * Based on the values here the SyncManager will determine the disposition of the
     25  * sync and whether or not a new sync operation needs to be scheduled in the future.
     26  *
     27  */
     28 public final class SyncResult implements Parcelable {
     29     /**
     30      * Used to indicate that the SyncAdapter is already performing a sync operation, though
     31      * not necessarily for the requested account and authority and that it wasn't able to
     32      * process this request. The SyncManager will reschedule the request to run later.
     33      */
     34     public final boolean syncAlreadyInProgress;
     35 
     36     /**
     37      * Used to indicate that the SyncAdapter determined that it would need to issue
     38      * too many delete operations to the server in order to satisfy the request
     39      * (as defined by the SyncAdapter). The SyncManager will record
     40      * that the sync request failed and will cause a System Notification to be created
     41      * asking the user what they want to do about this. It will give the user a chance to
     42      * choose between (1) go ahead even with those deletes, (2) revert the deletes,
     43      * or (3) take no action. If the user decides (1) or (2) the SyncManager will issue another
     44      * sync request with either {@link ContentResolver#SYNC_EXTRAS_OVERRIDE_TOO_MANY_DELETIONS}
     45      * or {@link ContentResolver#SYNC_EXTRAS_DISCARD_LOCAL_DELETIONS} set in the extras.
     46      * It is then up to the SyncAdapter to decide how to honor that request.
     47      */
     48     public boolean tooManyDeletions;
     49 
     50     /**
     51      * Used to indicate that the SyncAdapter experienced a hard error due to trying the same
     52      * operation too many times (as defined by the SyncAdapter). The SyncManager will record
     53      * that the sync request failed and it will not reschedule the request.
     54      */
     55     public boolean tooManyRetries;
     56 
     57     /**
     58      * Used to indicate that the SyncAdapter experienced a hard error due to an error it
     59      * received from interacting with the storage layer. The SyncManager will record that
     60      * the sync request failed and it will not reschedule the request.
     61      */
     62     public boolean databaseError;
     63 
     64     /**
     65      * If set the SyncManager will request an immediate sync with the same Account and authority
     66      * (but empty extras Bundle) as was used in the sync request.
     67      */
     68     public boolean fullSyncRequested;
     69 
     70     /**
     71      * This field is ignored by the SyncManager.
     72      */
     73     public boolean partialSyncUnavailable;
     74 
     75     /**
     76      * This field is ignored by the SyncManager.
     77      */
     78     public boolean moreRecordsToGet;
     79 
     80     /**
     81      * Used to indicate to the SyncManager that future sync requests that match the request's
     82      * Account and authority should be delayed at least this many seconds.
     83      */
     84     public long delayUntil;
     85 
     86     /**
     87      * Used to hold extras statistics about the sync operation. Some of these indicate that
     88      * the sync request resulted in a hard or soft error, others are for purely informational
     89      * purposes.
     90      */
     91     public final SyncStats stats;
     92 
     93     /**
     94      * This instance of a SyncResult is returned by the SyncAdapter in response to a
     95      * sync request when a sync is already underway. The SyncManager will reschedule the
     96      * sync request to try again later.
     97      */
     98     public static final SyncResult ALREADY_IN_PROGRESS;
     99 
    100     static {
    101         ALREADY_IN_PROGRESS = new SyncResult(true);
    102     }
    103 
    104     /**
    105      * Create a "clean" SyncResult. If this is returned without any changes then the
    106      * SyncManager will consider the sync to have completed successfully. The various fields
    107      * can be set by the SyncAdapter in order to give the SyncManager more information as to
    108      * the disposition of the sync.
    109      * <p>
    110      * The errors are classified into two broad categories: hard errors and soft errors.
    111      * Soft errors are retried with exponential backoff. Hard errors are not retried (except
    112      * when the hard error is for a {@link ContentResolver#SYNC_EXTRAS_UPLOAD} request,
    113      * in which the request is retryed without the {@link ContentResolver#SYNC_EXTRAS_UPLOAD}
    114      * extra set). The SyncManager checks the type of error by calling
    115      * {@link SyncResult#hasHardError()} and  {@link SyncResult#hasSoftError()}. If both are
    116      * true then the SyncManager treats it as a hard error, not a soft error.
    117      */
    118     public SyncResult() {
    119         this(false);
    120     }
    121 
    122     /**
    123      * Internal helper for creating a clean SyncResult or one that indicated that
    124      * a sync is already in progress.
    125      * @param syncAlreadyInProgress if true then set the {@link #syncAlreadyInProgress} flag
    126      */
    127     private SyncResult(boolean syncAlreadyInProgress) {
    128         this.syncAlreadyInProgress = syncAlreadyInProgress;
    129         this.tooManyDeletions = false;
    130         this.tooManyRetries = false;
    131         this.fullSyncRequested = false;
    132         this.partialSyncUnavailable = false;
    133         this.moreRecordsToGet = false;
    134         this.delayUntil = 0;
    135         this.stats = new SyncStats();
    136     }
    137 
    138     private SyncResult(Parcel parcel) {
    139         syncAlreadyInProgress = parcel.readInt() != 0;
    140         tooManyDeletions = parcel.readInt() != 0;
    141         tooManyRetries = parcel.readInt() != 0;
    142         databaseError = parcel.readInt() != 0;
    143         fullSyncRequested = parcel.readInt() != 0;
    144         partialSyncUnavailable = parcel.readInt() != 0;
    145         moreRecordsToGet = parcel.readInt() != 0;
    146         delayUntil = parcel.readLong();
    147         stats = new SyncStats(parcel);
    148     }
    149 
    150     /**
    151      * Convenience method for determining if the SyncResult indicates that a hard error
    152      * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
    153      * when it sees a hard error.
    154      * <p>
    155      * A hard error is indicated when any of the following is true:
    156      * <ul>
    157      * <li> {@link SyncStats#numParseExceptions} > 0
    158      * <li> {@link SyncStats#numConflictDetectedExceptions} > 0
    159      * <li> {@link SyncStats#numAuthExceptions} > 0
    160      * <li> {@link #tooManyDeletions}
    161      * <li> {@link #tooManyRetries}
    162      * <li> {@link #databaseError}
    163      * @return true if a hard error is indicated
    164      */
    165     public boolean hasHardError() {
    166         return stats.numParseExceptions > 0
    167                 || stats.numConflictDetectedExceptions > 0
    168                 || stats.numAuthExceptions > 0
    169                 || tooManyDeletions
    170                 || tooManyRetries
    171                 || databaseError;
    172     }
    173 
    174     /**
    175      * Convenience method for determining if the SyncResult indicates that a soft error
    176      * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
    177      * when it sees a soft error.
    178      * <p>
    179      * A soft error is indicated when any of the following is true:
    180      * <ul>
    181      * <li> {@link SyncStats#numIoExceptions} > 0
    182      * <li> {@link #syncAlreadyInProgress}
    183      * </ul>
    184      * @return true if a soft error is indicated
    185      */
    186     public boolean hasSoftError() {
    187         return syncAlreadyInProgress || stats.numIoExceptions > 0;
    188     }
    189 
    190     /**
    191      * A convenience method for determining of the SyncResult indicates that an error occurred.
    192      * @return true if either a soft or hard error occurred
    193      */
    194     public boolean hasError() {
    195         return hasSoftError() || hasHardError();
    196     }
    197 
    198     /**
    199      * Convenience method for determining if the Sync should be rescheduled after failing for some
    200      * reason.
    201      * @return true if the SyncManager should reschedule this sync.
    202      */
    203     public boolean madeSomeProgress() {
    204         return ((stats.numDeletes > 0) && !tooManyDeletions)
    205                 || stats.numInserts > 0
    206                 || stats.numUpdates > 0;
    207     }
    208 
    209     /**
    210      * Clears the SyncResult to a clean state. Throws an {@link UnsupportedOperationException}
    211      * if this is called when {@link #syncAlreadyInProgress} is set.
    212      */
    213     public void clear() {
    214         if (syncAlreadyInProgress) {
    215             throw new UnsupportedOperationException(
    216                     "you are not allowed to clear the ALREADY_IN_PROGRESS SyncStats");
    217         }
    218         tooManyDeletions = false;
    219         tooManyRetries = false;
    220         databaseError = false;
    221         fullSyncRequested = false;
    222         partialSyncUnavailable = false;
    223         moreRecordsToGet = false;
    224         delayUntil = 0;
    225         stats.clear();
    226     }
    227 
    228     public static final Creator<SyncResult> CREATOR = new Creator<SyncResult>() {
    229         public SyncResult createFromParcel(Parcel in) {
    230             return new SyncResult(in);
    231         }
    232 
    233         public SyncResult[] newArray(int size) {
    234             return new SyncResult[size];
    235         }
    236     };
    237 
    238     public int describeContents() {
    239         return 0;
    240     }
    241 
    242     public void writeToParcel(Parcel parcel, int flags) {
    243         parcel.writeInt(syncAlreadyInProgress ? 1 : 0);
    244         parcel.writeInt(tooManyDeletions ? 1 : 0);
    245         parcel.writeInt(tooManyRetries ? 1 : 0);
    246         parcel.writeInt(databaseError ? 1 : 0);
    247         parcel.writeInt(fullSyncRequested ? 1 : 0);
    248         parcel.writeInt(partialSyncUnavailable ? 1 : 0);
    249         parcel.writeInt(moreRecordsToGet ? 1 : 0);
    250         parcel.writeLong(delayUntil);
    251         stats.writeToParcel(parcel, flags);
    252     }
    253 
    254     @Override
    255     public String toString() {
    256         StringBuilder sb = new StringBuilder();
    257         sb.append("SyncResult:");
    258         if (syncAlreadyInProgress) {
    259             sb.append(" syncAlreadyInProgress: ").append(syncAlreadyInProgress);
    260         }
    261         if (tooManyDeletions) sb.append(" tooManyDeletions: ").append(tooManyDeletions);
    262         if (tooManyRetries) sb.append(" tooManyRetries: ").append(tooManyRetries);
    263         if (databaseError) sb.append(" databaseError: ").append(databaseError);
    264         if (fullSyncRequested) sb.append(" fullSyncRequested: ").append(fullSyncRequested);
    265         if (partialSyncUnavailable) {
    266             sb.append(" partialSyncUnavailable: ").append(partialSyncUnavailable);
    267         }
    268         if (moreRecordsToGet) sb.append(" moreRecordsToGet: ").append(moreRecordsToGet);
    269         if (delayUntil > 0) sb.append(" delayUntil: ").append(delayUntil);
    270         sb.append(stats);
    271         return sb.toString();
    272     }
    273 
    274     /**
    275      * Generates a debugging string indicating the status.
    276      * The string consist of a sequence of code letter followed by the count.
    277      * Code letters are f - fullSyncRequested, r - partialSyncUnavailable,
    278      * X - hardError, e - numParseExceptions, c - numConflictDetectedExceptions,
    279      * a - numAuthExceptions, D - tooManyDeletions, R - tooManyRetries,
    280      * b - databaseError, x - softError, l - syncAlreadyInProgress,
    281      * I - numIoExceptions
    282      * @return debugging string.
    283      */
    284     public String toDebugString() {
    285         StringBuffer sb = new StringBuffer();
    286 
    287         if (fullSyncRequested) {
    288             sb.append("f1");
    289         }
    290         if (partialSyncUnavailable) {
    291             sb.append("r1");
    292         }
    293         if (hasHardError()) {
    294             sb.append("X1");
    295         }
    296         if (stats.numParseExceptions > 0) {
    297             sb.append("e").append(stats.numParseExceptions);
    298         }
    299         if (stats.numConflictDetectedExceptions > 0) {
    300             sb.append("c").append(stats.numConflictDetectedExceptions);
    301         }
    302         if (stats.numAuthExceptions > 0) {
    303             sb.append("a").append(stats.numAuthExceptions);
    304         }
    305         if (tooManyDeletions) {
    306             sb.append("D1");
    307         }
    308         if (tooManyRetries) {
    309             sb.append("R1");
    310         }
    311         if (databaseError) {
    312             sb.append("b1");
    313         }
    314         if (hasSoftError()) {
    315             sb.append("x1");
    316         }
    317         if (syncAlreadyInProgress) {
    318             sb.append("l1");
    319         }
    320         if (stats.numIoExceptions > 0) {
    321             sb.append("I").append(stats.numIoExceptions);
    322         }
    323         return sb.toString();
    324     }
    325 }
    326