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 until a time in seconds since Java epoch. 83 * 84 * <p>For example, if you want to delay the next sync for at least 5 minutes, then: 85 * <pre> 86 * result.delayUntil = (System.currentTimeMillis() / 1000) + 5 * 60; 87 * </pre> 88 * 89 * <p>By default, when a sync fails, the system retries later with an exponential back-off 90 * with the system default initial delay time, which always wins over {@link #delayUntil} -- 91 * i.e. if the system back-off time is larger than {@link #delayUntil}, {@link #delayUntil} 92 * will essentially be ignored. 93 */ 94 public long delayUntil; 95 96 /** 97 * Used to hold extras statistics about the sync operation. Some of these indicate that 98 * the sync request resulted in a hard or soft error, others are for purely informational 99 * purposes. 100 */ 101 public final SyncStats stats; 102 103 /** 104 * This instance of a SyncResult is returned by the SyncAdapter in response to a 105 * sync request when a sync is already underway. The SyncManager will reschedule the 106 * sync request to try again later. 107 */ 108 public static final SyncResult ALREADY_IN_PROGRESS; 109 110 static { 111 ALREADY_IN_PROGRESS = new SyncResult(true); 112 } 113 114 /** 115 * Create a "clean" SyncResult. If this is returned without any changes then the 116 * SyncManager will consider the sync to have completed successfully. The various fields 117 * can be set by the SyncAdapter in order to give the SyncManager more information as to 118 * the disposition of the sync. 119 * <p> 120 * The errors are classified into two broad categories: hard errors and soft errors. 121 * Soft errors are retried with exponential backoff. Hard errors are not retried (except 122 * when the hard error is for a {@link ContentResolver#SYNC_EXTRAS_UPLOAD} request, 123 * in which the request is retryed without the {@link ContentResolver#SYNC_EXTRAS_UPLOAD} 124 * extra set). The SyncManager checks the type of error by calling 125 * {@link SyncResult#hasHardError()} and {@link SyncResult#hasSoftError()}. If both are 126 * true then the SyncManager treats it as a hard error, not a soft error. 127 */ SyncResult()128 public SyncResult() { 129 this(false); 130 } 131 132 /** 133 * Internal helper for creating a clean SyncResult or one that indicated that 134 * a sync is already in progress. 135 * @param syncAlreadyInProgress if true then set the {@link #syncAlreadyInProgress} flag 136 */ SyncResult(boolean syncAlreadyInProgress)137 private SyncResult(boolean syncAlreadyInProgress) { 138 this.syncAlreadyInProgress = syncAlreadyInProgress; 139 this.tooManyDeletions = false; 140 this.tooManyRetries = false; 141 this.fullSyncRequested = false; 142 this.partialSyncUnavailable = false; 143 this.moreRecordsToGet = false; 144 this.delayUntil = 0; 145 this.stats = new SyncStats(); 146 } 147 SyncResult(Parcel parcel)148 private SyncResult(Parcel parcel) { 149 syncAlreadyInProgress = parcel.readInt() != 0; 150 tooManyDeletions = parcel.readInt() != 0; 151 tooManyRetries = parcel.readInt() != 0; 152 databaseError = parcel.readInt() != 0; 153 fullSyncRequested = parcel.readInt() != 0; 154 partialSyncUnavailable = parcel.readInt() != 0; 155 moreRecordsToGet = parcel.readInt() != 0; 156 delayUntil = parcel.readLong(); 157 stats = new SyncStats(parcel); 158 } 159 160 /** 161 * Convenience method for determining if the SyncResult indicates that a hard error 162 * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does 163 * when it sees a hard error. 164 * <p> 165 * A hard error is indicated when any of the following is true: 166 * <ul> 167 * <li> {@link SyncStats#numParseExceptions} > 0 168 * <li> {@link SyncStats#numConflictDetectedExceptions} > 0 169 * <li> {@link SyncStats#numAuthExceptions} > 0 170 * <li> {@link #tooManyDeletions} 171 * <li> {@link #tooManyRetries} 172 * <li> {@link #databaseError} 173 * @return true if a hard error is indicated 174 */ hasHardError()175 public boolean hasHardError() { 176 return stats.numParseExceptions > 0 177 || stats.numConflictDetectedExceptions > 0 178 || stats.numAuthExceptions > 0 179 || tooManyDeletions 180 || tooManyRetries 181 || databaseError; 182 } 183 184 /** 185 * Convenience method for determining if the SyncResult indicates that a soft error 186 * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does 187 * when it sees a soft error. 188 * <p> 189 * A soft error is indicated when any of the following is true: 190 * <ul> 191 * <li> {@link SyncStats#numIoExceptions} > 0 192 * <li> {@link #syncAlreadyInProgress} 193 * </ul> 194 * @return true if a soft error is indicated 195 */ hasSoftError()196 public boolean hasSoftError() { 197 return syncAlreadyInProgress || stats.numIoExceptions > 0; 198 } 199 200 /** 201 * A convenience method for determining of the SyncResult indicates that an error occurred. 202 * @return true if either a soft or hard error occurred 203 */ hasError()204 public boolean hasError() { 205 return hasSoftError() || hasHardError(); 206 } 207 208 /** 209 * Convenience method for determining if the Sync should be rescheduled after failing for some 210 * reason. 211 * @return true if the SyncManager should reschedule this sync. 212 */ madeSomeProgress()213 public boolean madeSomeProgress() { 214 return ((stats.numDeletes > 0) && !tooManyDeletions) 215 || stats.numInserts > 0 216 || stats.numUpdates > 0; 217 } 218 219 /** 220 * Clears the SyncResult to a clean state. Throws an {@link UnsupportedOperationException} 221 * if this is called when {@link #syncAlreadyInProgress} is set. 222 */ clear()223 public void clear() { 224 if (syncAlreadyInProgress) { 225 throw new UnsupportedOperationException( 226 "you are not allowed to clear the ALREADY_IN_PROGRESS SyncStats"); 227 } 228 tooManyDeletions = false; 229 tooManyRetries = false; 230 databaseError = false; 231 fullSyncRequested = false; 232 partialSyncUnavailable = false; 233 moreRecordsToGet = false; 234 delayUntil = 0; 235 stats.clear(); 236 } 237 238 public static final @android.annotation.NonNull Creator<SyncResult> CREATOR = new Creator<SyncResult>() { 239 public SyncResult createFromParcel(Parcel in) { 240 return new SyncResult(in); 241 } 242 243 public SyncResult[] newArray(int size) { 244 return new SyncResult[size]; 245 } 246 }; 247 describeContents()248 public int describeContents() { 249 return 0; 250 } 251 writeToParcel(Parcel parcel, int flags)252 public void writeToParcel(Parcel parcel, int flags) { 253 parcel.writeInt(syncAlreadyInProgress ? 1 : 0); 254 parcel.writeInt(tooManyDeletions ? 1 : 0); 255 parcel.writeInt(tooManyRetries ? 1 : 0); 256 parcel.writeInt(databaseError ? 1 : 0); 257 parcel.writeInt(fullSyncRequested ? 1 : 0); 258 parcel.writeInt(partialSyncUnavailable ? 1 : 0); 259 parcel.writeInt(moreRecordsToGet ? 1 : 0); 260 parcel.writeLong(delayUntil); 261 stats.writeToParcel(parcel, flags); 262 } 263 264 @Override toString()265 public String toString() { 266 StringBuilder sb = new StringBuilder(); 267 sb.append("SyncResult:"); 268 if (syncAlreadyInProgress) { 269 sb.append(" syncAlreadyInProgress: ").append(syncAlreadyInProgress); 270 } 271 if (tooManyDeletions) sb.append(" tooManyDeletions: ").append(tooManyDeletions); 272 if (tooManyRetries) sb.append(" tooManyRetries: ").append(tooManyRetries); 273 if (databaseError) sb.append(" databaseError: ").append(databaseError); 274 if (fullSyncRequested) sb.append(" fullSyncRequested: ").append(fullSyncRequested); 275 if (partialSyncUnavailable) { 276 sb.append(" partialSyncUnavailable: ").append(partialSyncUnavailable); 277 } 278 if (moreRecordsToGet) sb.append(" moreRecordsToGet: ").append(moreRecordsToGet); 279 if (delayUntil > 0) sb.append(" delayUntil: ").append(delayUntil); 280 sb.append(stats); 281 return sb.toString(); 282 } 283 284 /** 285 * Generates a debugging string indicating the status. 286 * The string consist of a sequence of code letter followed by the count. 287 * Code letters are f - fullSyncRequested, r - partialSyncUnavailable, 288 * X - hardError, e - numParseExceptions, c - numConflictDetectedExceptions, 289 * a - numAuthExceptions, D - tooManyDeletions, R - tooManyRetries, 290 * b - databaseError, x - softError, l - syncAlreadyInProgress, 291 * I - numIoExceptions 292 * @return debugging string. 293 */ toDebugString()294 public String toDebugString() { 295 StringBuilder sb = new StringBuilder(); 296 297 if (fullSyncRequested) { 298 sb.append("f1"); 299 } 300 if (partialSyncUnavailable) { 301 sb.append("r1"); 302 } 303 if (hasHardError()) { 304 sb.append("X1"); 305 } 306 if (stats.numParseExceptions > 0) { 307 sb.append("e").append(stats.numParseExceptions); 308 } 309 if (stats.numConflictDetectedExceptions > 0) { 310 sb.append("c").append(stats.numConflictDetectedExceptions); 311 } 312 if (stats.numAuthExceptions > 0) { 313 sb.append("a").append(stats.numAuthExceptions); 314 } 315 if (tooManyDeletions) { 316 sb.append("D1"); 317 } 318 if (tooManyRetries) { 319 sb.append("R1"); 320 } 321 if (databaseError) { 322 sb.append("b1"); 323 } 324 if (hasSoftError()) { 325 sb.append("x1"); 326 } 327 if (syncAlreadyInProgress) { 328 sb.append("l1"); 329 } 330 if (stats.numIoExceptions > 0) { 331 sb.append("I").append(stats.numIoExceptions); 332 } 333 return sb.toString(); 334 } 335 } 336