321 lines
12 KiB
Java
321 lines
12 KiB
Java
|
/*
|
||
|
|
* Copyright (C) 2008 The Android Open Source Project
|
||
|
|
*
|
||
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
|
* you may not use this file except in compliance with the License.
|
||
|
|
* You may obtain a copy of the License at
|
||
|
|
*
|
||
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
*
|
||
|
|
* Unless required by applicable law or agreed to in writing, software
|
||
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
|
* See the License for the specific language governing permissions and
|
||
|
|
* limitations under the License.
|
||
|
|
*/
|
||
|
|
|
||
|
|
package android.content;
|
||
|
|
|
||
|
|
import android.os.Parcel;
|
||
|
|
import android.os.Parcelable;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This class is used to communicate the results of a sync operation to the SyncManager.
|
||
|
|
* Based on the values here the SyncManager will determine the disposition of the
|
||
|
|
* sync and whether or not a new sync operation needs to be scheduled in the future.
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
public final class SyncResult implements Parcelable {
|
||
|
|
/**
|
||
|
|
* Used to indicate that the SyncAdapter is already performing a sync operation, though
|
||
|
|
* not necessarily for the requested account and authority and that it wasn't able to
|
||
|
|
* process this request. The SyncManager will reschedule the request to run later.
|
||
|
|
*/
|
||
|
|
public final boolean syncAlreadyInProgress;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Used to indicate that the SyncAdapter determined that it would need to issue
|
||
|
|
* too many delete operations to the server in order to satisfy the request
|
||
|
|
* (as defined by the SyncAdapter). The SyncManager will record
|
||
|
|
* that the sync request failed and will cause a System Notification to be created
|
||
|
|
* asking the user what they want to do about this. It will give the user a chance to
|
||
|
|
* choose between (1) go ahead even with those deletes, (2) revert the deletes,
|
||
|
|
* or (3) take no action. If the user decides (1) or (2) the SyncManager will issue another
|
||
|
|
* sync request with either {@link ContentResolver#SYNC_EXTRAS_OVERRIDE_TOO_MANY_DELETIONS}
|
||
|
|
* or {@link ContentResolver#SYNC_EXTRAS_DISCARD_LOCAL_DELETIONS} set in the extras.
|
||
|
|
* It is then up to the SyncAdapter to decide how to honor that request.
|
||
|
|
*/
|
||
|
|
public boolean tooManyDeletions;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Used to indicate that the SyncAdapter experienced a hard error due to trying the same
|
||
|
|
* operation too many times (as defined by the SyncAdapter). The SyncManager will record
|
||
|
|
* that the sync request failed and it will not reschedule the request.
|
||
|
|
*/
|
||
|
|
public boolean tooManyRetries;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Used to indicate that the SyncAdapter experienced a hard error due to an error it
|
||
|
|
* received from interacting with the storage later. The SyncManager will record that
|
||
|
|
* the sync request failed and it will not reschedule the request.
|
||
|
|
*/
|
||
|
|
public boolean databaseError;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* If set the SyncManager will request an immediate sync with the same Account and authority
|
||
|
|
* (but empty extras Bundle) as was used in the sync request.
|
||
|
|
*/
|
||
|
|
public boolean fullSyncRequested;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This field is ignored by the SyncManager.
|
||
|
|
*/
|
||
|
|
public boolean partialSyncUnavailable;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This field is ignored by the SyncManager.
|
||
|
|
*/
|
||
|
|
public boolean moreRecordsToGet;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Used to indicate to the SyncManager that future sync requests that match the request's
|
||
|
|
* Account and authority should be delayed at least this many seconds.
|
||
|
|
*/
|
||
|
|
public long delayUntil;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Used to hold extras statistics about the sync operation. Some of these indicate that
|
||
|
|
* the sync request resulted in a hard or soft error, others are for purely informational
|
||
|
|
* purposes.
|
||
|
|
*/
|
||
|
|
public final SyncStats stats;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This instance of a SyncResult is returned by the SyncAdapter in response to a
|
||
|
|
* sync request when a sync is already underway. The SyncManager will reschedule the
|
||
|
|
* sync request to try again later.
|
||
|
|
*/
|
||
|
|
public static final SyncResult ALREADY_IN_PROGRESS;
|
||
|
|
|
||
|
|
static {
|
||
|
|
ALREADY_IN_PROGRESS = new SyncResult(true);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Create a "clean" SyncResult. If this is returned without any changes then the
|
||
|
|
* SyncManager will consider the sync to have completed successfully. The various fields
|
||
|
|
* can be set by the SyncAdapter in order to give the SyncManager more information as to
|
||
|
|
* the disposition of the sync.
|
||
|
|
* <p>
|
||
|
|
* The errors are classified into two broad categories: hard errors and soft errors.
|
||
|
|
* Soft errors are retried with exponential backoff. Hard errors are not retried (except
|
||
|
|
* when the hard error is for a {@link ContentResolver#SYNC_EXTRAS_UPLOAD} request,
|
||
|
|
* in which the request is retryed without the {@link ContentResolver#SYNC_EXTRAS_UPLOAD}
|
||
|
|
* extra set). The SyncManager checks the type of error by calling
|
||
|
|
* {@link SyncResult#hasHardError()} and {@link SyncResult#hasSoftError()}. If both are
|
||
|
|
* true then the SyncManager treats it as a hard error, not a soft error.
|
||
|
|
*/
|
||
|
|
public SyncResult() {
|
||
|
|
this(false);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Internal helper for creating a clean SyncResult or one that indicated that
|
||
|
|
* a sync is already in progress.
|
||
|
|
* @param syncAlreadyInProgress if true then set the {@link #syncAlreadyInProgress} flag
|
||
|
|
*/
|
||
|
|
private SyncResult(boolean syncAlreadyInProgress) {
|
||
|
|
this.syncAlreadyInProgress = syncAlreadyInProgress;
|
||
|
|
this.tooManyDeletions = false;
|
||
|
|
this.tooManyRetries = false;
|
||
|
|
this.fullSyncRequested = false;
|
||
|
|
this.partialSyncUnavailable = false;
|
||
|
|
this.moreRecordsToGet = false;
|
||
|
|
this.delayUntil = 0;
|
||
|
|
this.stats = new SyncStats();
|
||
|
|
}
|
||
|
|
|
||
|
|
private SyncResult(Parcel parcel) {
|
||
|
|
syncAlreadyInProgress = parcel.readInt() != 0;
|
||
|
|
tooManyDeletions = parcel.readInt() != 0;
|
||
|
|
tooManyRetries = parcel.readInt() != 0;
|
||
|
|
databaseError = parcel.readInt() != 0;
|
||
|
|
fullSyncRequested = parcel.readInt() != 0;
|
||
|
|
partialSyncUnavailable = parcel.readInt() != 0;
|
||
|
|
moreRecordsToGet = parcel.readInt() != 0;
|
||
|
|
delayUntil = parcel.readLong();
|
||
|
|
stats = new SyncStats(parcel);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Convenience method for determining if the SyncResult indicates that a hard error
|
||
|
|
* occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
|
||
|
|
* when it sees a hard error.
|
||
|
|
* <p>
|
||
|
|
* A hard error is indicated when any of the following is true:
|
||
|
|
* <ul>
|
||
|
|
* <li> {@link SyncStats#numParseExceptions} > 0
|
||
|
|
* <li> {@link SyncStats#numConflictDetectedExceptions} > 0
|
||
|
|
* <li> {@link SyncStats#numAuthExceptions} > 0
|
||
|
|
* <li> {@link #tooManyDeletions}
|
||
|
|
* <li> {@link #tooManyRetries}
|
||
|
|
* <li> {@link #databaseError}
|
||
|
|
* @return true if a hard error is indicated
|
||
|
|
*/
|
||
|
|
public boolean hasHardError() {
|
||
|
|
return stats.numParseExceptions > 0
|
||
|
|
|| stats.numConflictDetectedExceptions > 0
|
||
|
|
|| stats.numAuthExceptions > 0
|
||
|
|
|| tooManyDeletions
|
||
|
|
|| tooManyRetries
|
||
|
|
|| databaseError;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Convenience method for determining if the SyncResult indicates that a soft error
|
||
|
|
* occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
|
||
|
|
* when it sees a soft error.
|
||
|
|
* <p>
|
||
|
|
* A soft error is indicated when any of the following is true:
|
||
|
|
* <ul>
|
||
|
|
* <li> {@link SyncStats#numIoExceptions} > 0
|
||
|
|
* <li> {@link #syncAlreadyInProgress}
|
||
|
|
* </ul>
|
||
|
|
* @return true if a hard error is indicated
|
||
|
|
*/
|
||
|
|
public boolean hasSoftError() {
|
||
|
|
return syncAlreadyInProgress || stats.numIoExceptions > 0;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A convenience method for determining of the SyncResult indicates that an error occurred.
|
||
|
|
* @return true if either a soft or hard error occurred
|
||
|
|
*/
|
||
|
|
public boolean hasError() {
|
||
|
|
return hasSoftError() || hasHardError();
|
||
|
|
}
|
||
|
|
|
||
|
|
public boolean madeSomeProgress() {
|
||
|
|
return ((stats.numDeletes > 0) && !tooManyDeletions)
|
||
|
|
|| stats.numInserts > 0
|
||
|
|
|| stats.numUpdates > 0;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Clears the SyncResult to a clean state. Throws an {@link UnsupportedOperationException}
|
||
|
|
* if this is called when {@link #syncAlreadyInProgress} is set.
|
||
|
|
*/
|
||
|
|
public void clear() {
|
||
|
|
if (syncAlreadyInProgress) {
|
||
|
|
throw new UnsupportedOperationException(
|
||
|
|
"you are not allowed to clear the ALREADY_IN_PROGRESS SyncStats");
|
||
|
|
}
|
||
|
|
tooManyDeletions = false;
|
||
|
|
tooManyRetries = false;
|
||
|
|
databaseError = false;
|
||
|
|
fullSyncRequested = false;
|
||
|
|
partialSyncUnavailable = false;
|
||
|
|
moreRecordsToGet = false;
|
||
|
|
delayUntil = 0;
|
||
|
|
stats.clear();
|
||
|
|
}
|
||
|
|
|
||
|
|
public static final Creator<SyncResult> CREATOR = new Creator<SyncResult>() {
|
||
|
|
public SyncResult createFromParcel(Parcel in) {
|
||
|
|
return new SyncResult(in);
|
||
|
|
}
|
||
|
|
|
||
|
|
public SyncResult[] newArray(int size) {
|
||
|
|
return new SyncResult[size];
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
public int describeContents() {
|
||
|
|
return 0;
|
||
|
|
}
|
||
|
|
|
||
|
|
public void writeToParcel(Parcel parcel, int flags) {
|
||
|
|
parcel.writeInt(syncAlreadyInProgress ? 1 : 0);
|
||
|
|
parcel.writeInt(tooManyDeletions ? 1 : 0);
|
||
|
|
parcel.writeInt(tooManyRetries ? 1 : 0);
|
||
|
|
parcel.writeInt(databaseError ? 1 : 0);
|
||
|
|
parcel.writeInt(fullSyncRequested ? 1 : 0);
|
||
|
|
parcel.writeInt(partialSyncUnavailable ? 1 : 0);
|
||
|
|
parcel.writeInt(moreRecordsToGet ? 1 : 0);
|
||
|
|
parcel.writeLong(delayUntil);
|
||
|
|
stats.writeToParcel(parcel, flags);
|
||
|
|
}
|
||
|
|
|
||
|
|
@Override
|
||
|
|
public String toString() {
|
||
|
|
StringBuilder sb = new StringBuilder();
|
||
|
|
sb.append("SyncResult:");
|
||
|
|
if (syncAlreadyInProgress) {
|
||
|
|
sb.append(" syncAlreadyInProgress: ").append(syncAlreadyInProgress);
|
||
|
|
}
|
||
|
|
if (tooManyDeletions) sb.append(" tooManyDeletions: ").append(tooManyDeletions);
|
||
|
|
if (tooManyRetries) sb.append(" tooManyRetries: ").append(tooManyRetries);
|
||
|
|
if (databaseError) sb.append(" databaseError: ").append(databaseError);
|
||
|
|
if (fullSyncRequested) sb.append(" fullSyncRequested: ").append(fullSyncRequested);
|
||
|
|
if (partialSyncUnavailable) {
|
||
|
|
sb.append(" partialSyncUnavailable: ").append(partialSyncUnavailable);
|
||
|
|
}
|
||
|
|
if (moreRecordsToGet) sb.append(" moreRecordsToGet: ").append(moreRecordsToGet);
|
||
|
|
if (delayUntil > 0) sb.append(" delayUntil: ").append(delayUntil);
|
||
|
|
sb.append(stats);
|
||
|
|
return sb.toString();
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Generates a debugging string indicating the status.
|
||
|
|
* The string consist of a sequence of code letter followed by the count.
|
||
|
|
* Code letters are f - fullSyncRequested, r - partialSyncUnavailable,
|
||
|
|
* X - hardError, e - numParseExceptions, c - numConflictDetectedExceptions,
|
||
|
|
* a - numAuthExceptions, D - tooManyDeletions, R - tooManyRetries,
|
||
|
|
* b - databaseError, x - softError, l - syncAlreadyInProgress,
|
||
|
|
* I - numIoExceptions
|
||
|
|
* @return debugging string.
|
||
|
|
*/
|
||
|
|
public String toDebugString() {
|
||
|
|
StringBuffer sb = new StringBuffer();
|
||
|
|
|
||
|
|
if (fullSyncRequested) {
|
||
|
|
sb.append("f1");
|
||
|
|
}
|
||
|
|
if (partialSyncUnavailable) {
|
||
|
|
sb.append("r1");
|
||
|
|
}
|
||
|
|
if (hasHardError()) {
|
||
|
|
sb.append("X1");
|
||
|
|
}
|
||
|
|
if (stats.numParseExceptions > 0) {
|
||
|
|
sb.append("e").append(stats.numParseExceptions);
|
||
|
|
}
|
||
|
|
if (stats.numConflictDetectedExceptions > 0) {
|
||
|
|
sb.append("c").append(stats.numConflictDetectedExceptions);
|
||
|
|
}
|
||
|
|
if (stats.numAuthExceptions > 0) {
|
||
|
|
sb.append("a").append(stats.numAuthExceptions);
|
||
|
|
}
|
||
|
|
if (tooManyDeletions) {
|
||
|
|
sb.append("D1");
|
||
|
|
}
|
||
|
|
if (tooManyRetries) {
|
||
|
|
sb.append("R1");
|
||
|
|
}
|
||
|
|
if (databaseError) {
|
||
|
|
sb.append("b1");
|
||
|
|
}
|
||
|
|
if (hasSoftError()) {
|
||
|
|
sb.append("x1");
|
||
|
|
}
|
||
|
|
if (syncAlreadyInProgress) {
|
||
|
|
sb.append("l1");
|
||
|
|
}
|
||
|
|
if (stats.numIoExceptions > 0) {
|
||
|
|
sb.append("I").append(stats.numIoExceptions);
|
||
|
|
}
|
||
|
|
return sb.toString();
|
||
|
|
}
|
||
|
|
}
|