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 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         StringBuffer sb = new StringBuffer();
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