Kenny Root | 15a4d2f | 2010-03-11 18:20:12 -0800 | [diff] [blame] | 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 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 17 | package android.content; |
| 18 | |
| 19 | import android.os.Parcel; |
| 20 | import android.os.Parcelable; |
| 21 | |
| 22 | /** |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | * |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 27 | */ |
| 28 | public final class SyncResult implements Parcelable { |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 34 | public final boolean syncAlreadyInProgress; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 48 | public boolean tooManyDeletions; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 55 | public boolean tooManyRetries; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 later. The SyncManager will record that |
| 60 | * the sync request failed and it will not reschedule the request. |
| 61 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 62 | public boolean databaseError; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 68 | public boolean fullSyncRequested; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 69 | |
| 70 | /** |
| 71 | * This field is ignored by the SyncManager. |
| 72 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 73 | public boolean partialSyncUnavailable; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 74 | |
| 75 | /** |
| 76 | * This field is ignored by the SyncManager. |
| 77 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 78 | public boolean moreRecordsToGet; |
Fred Quintana | 307da1a | 2010-01-21 14:24:20 -0800 | [diff] [blame] | 79 | |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
Fred Quintana | 307da1a | 2010-01-21 14:24:20 -0800 | [diff] [blame] | 84 | public long delayUntil; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 91 | public final SyncStats stats; |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 98 | public static final SyncResult ALREADY_IN_PROGRESS; |
| 99 | |
| 100 | static { |
| 101 | ALREADY_IN_PROGRESS = new SyncResult(true); |
| 102 | } |
| 103 | |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 118 | public SyncResult() { |
| 119 | this(false); |
| 120 | } |
| 121 | |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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; |
Fred Quintana | 307da1a | 2010-01-21 14:24:20 -0800 | [diff] [blame] | 134 | this.delayUntil = 0; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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; |
Fred Quintana | 307da1a | 2010-01-21 14:24:20 -0800 | [diff] [blame] | 146 | delayUntil = parcel.readLong(); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 147 | stats = new SyncStats(parcel); |
| 148 | } |
| 149 | |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 hard error is indicated |
| 185 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 186 | public boolean hasSoftError() { |
| 187 | return syncAlreadyInProgress || stats.numIoExceptions > 0; |
| 188 | } |
| 189 | |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 194 | public boolean hasError() { |
| 195 | return hasSoftError() || hasHardError(); |
| 196 | } |
| 197 | |
| 198 | public boolean madeSomeProgress() { |
| 199 | return ((stats.numDeletes > 0) && !tooManyDeletions) |
| 200 | || stats.numInserts > 0 |
| 201 | || stats.numUpdates > 0; |
| 202 | } |
| 203 | |
Fred Quintana | 20c640e | 2010-04-26 17:38:56 -0700 | [diff] [blame] | 204 | /** |
| 205 | * Clears the SyncResult to a clean state. Throws an {@link UnsupportedOperationException} |
| 206 | * if this is called when {@link #syncAlreadyInProgress} is set. |
| 207 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 208 | public void clear() { |
| 209 | if (syncAlreadyInProgress) { |
| 210 | throw new UnsupportedOperationException( |
| 211 | "you are not allowed to clear the ALREADY_IN_PROGRESS SyncStats"); |
| 212 | } |
| 213 | tooManyDeletions = false; |
| 214 | tooManyRetries = false; |
| 215 | databaseError = false; |
| 216 | fullSyncRequested = false; |
| 217 | partialSyncUnavailable = false; |
| 218 | moreRecordsToGet = false; |
Fred Quintana | 307da1a | 2010-01-21 14:24:20 -0800 | [diff] [blame] | 219 | delayUntil = 0; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 220 | stats.clear(); |
| 221 | } |
| 222 | |
| 223 | public static final Creator<SyncResult> CREATOR = new Creator<SyncResult>() { |
| 224 | public SyncResult createFromParcel(Parcel in) { |
| 225 | return new SyncResult(in); |
| 226 | } |
| 227 | |
| 228 | public SyncResult[] newArray(int size) { |
| 229 | return new SyncResult[size]; |
| 230 | } |
| 231 | }; |
| 232 | |
| 233 | public int describeContents() { |
| 234 | return 0; |
| 235 | } |
| 236 | |
| 237 | public void writeToParcel(Parcel parcel, int flags) { |
| 238 | parcel.writeInt(syncAlreadyInProgress ? 1 : 0); |
| 239 | parcel.writeInt(tooManyDeletions ? 1 : 0); |
| 240 | parcel.writeInt(tooManyRetries ? 1 : 0); |
| 241 | parcel.writeInt(databaseError ? 1 : 0); |
| 242 | parcel.writeInt(fullSyncRequested ? 1 : 0); |
| 243 | parcel.writeInt(partialSyncUnavailable ? 1 : 0); |
| 244 | parcel.writeInt(moreRecordsToGet ? 1 : 0); |
Fred Quintana | 307da1a | 2010-01-21 14:24:20 -0800 | [diff] [blame] | 245 | parcel.writeLong(delayUntil); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 246 | stats.writeToParcel(parcel, flags); |
| 247 | } |
| 248 | |
| 249 | @Override |
| 250 | public String toString() { |
| 251 | StringBuilder sb = new StringBuilder(); |
Fred Quintana | 7770975 | 2009-08-20 17:18:58 -0700 | [diff] [blame] | 252 | sb.append("SyncResult:"); |
| 253 | if (syncAlreadyInProgress) { |
| 254 | sb.append(" syncAlreadyInProgress: ").append(syncAlreadyInProgress); |
| 255 | } |
| 256 | if (tooManyDeletions) sb.append(" tooManyDeletions: ").append(tooManyDeletions); |
| 257 | if (tooManyRetries) sb.append(" tooManyRetries: ").append(tooManyRetries); |
| 258 | if (databaseError) sb.append(" databaseError: ").append(databaseError); |
| 259 | if (fullSyncRequested) sb.append(" fullSyncRequested: ").append(fullSyncRequested); |
| 260 | if (partialSyncUnavailable) { |
| 261 | sb.append(" partialSyncUnavailable: ").append(partialSyncUnavailable); |
| 262 | } |
| 263 | if (moreRecordsToGet) sb.append(" moreRecordsToGet: ").append(moreRecordsToGet); |
Fred Quintana | 307da1a | 2010-01-21 14:24:20 -0800 | [diff] [blame] | 264 | if (delayUntil > 0) sb.append(" delayUntil: ").append(delayUntil); |
Fred Quintana | 7770975 | 2009-08-20 17:18:58 -0700 | [diff] [blame] | 265 | sb.append(stats); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 266 | return sb.toString(); |
| 267 | } |
| 268 | |
| 269 | /** |
| 270 | * Generates a debugging string indicating the status. |
| 271 | * The string consist of a sequence of code letter followed by the count. |
| 272 | * Code letters are f - fullSyncRequested, r - partialSyncUnavailable, |
| 273 | * X - hardError, e - numParseExceptions, c - numConflictDetectedExceptions, |
| 274 | * a - numAuthExceptions, D - tooManyDeletions, R - tooManyRetries, |
| 275 | * b - databaseError, x - softError, l - syncAlreadyInProgress, |
| 276 | * I - numIoExceptions |
| 277 | * @return debugging string. |
| 278 | */ |
| 279 | public String toDebugString() { |
| 280 | StringBuffer sb = new StringBuffer(); |
| 281 | |
| 282 | if (fullSyncRequested) { |
| 283 | sb.append("f1"); |
| 284 | } |
| 285 | if (partialSyncUnavailable) { |
| 286 | sb.append("r1"); |
| 287 | } |
| 288 | if (hasHardError()) { |
| 289 | sb.append("X1"); |
| 290 | } |
| 291 | if (stats.numParseExceptions > 0) { |
| 292 | sb.append("e").append(stats.numParseExceptions); |
| 293 | } |
| 294 | if (stats.numConflictDetectedExceptions > 0) { |
| 295 | sb.append("c").append(stats.numConflictDetectedExceptions); |
| 296 | } |
| 297 | if (stats.numAuthExceptions > 0) { |
| 298 | sb.append("a").append(stats.numAuthExceptions); |
| 299 | } |
| 300 | if (tooManyDeletions) { |
| 301 | sb.append("D1"); |
| 302 | } |
| 303 | if (tooManyRetries) { |
| 304 | sb.append("R1"); |
| 305 | } |
| 306 | if (databaseError) { |
| 307 | sb.append("b1"); |
| 308 | } |
| 309 | if (hasSoftError()) { |
| 310 | sb.append("x1"); |
| 311 | } |
| 312 | if (syncAlreadyInProgress) { |
| 313 | sb.append("l1"); |
| 314 | } |
| 315 | if (stats.numIoExceptions > 0) { |
| 316 | sb.append("I").append(stats.numIoExceptions); |
| 317 | } |
| 318 | return sb.toString(); |
| 319 | } |
| 320 | } |