https://source.android.com/ 
/*
 * 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.

/**
 * 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.

/**
     * 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 ContentResolver.SYNC_EXTRAS_OVERRIDE_TOO_MANY_DELETIONS or ContentResolver.SYNC_EXTRAS_DISCARD_LOCAL_DELETIONS set in the extras. It is then up to the SyncAdapter to decide how to honor that request. 
/**
     * 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.

/**
     * 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 layer. The SyncManager will record that
the sync request failed and it will not reschedule the request.

/**
     * Used to indicate that the SyncAdapter experienced a hard error due to an error it
     * received from interacting with the storage layer. 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.

/**
     * 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.

/**
     * This field is ignored by the SyncManager.
     */
    public boolean partialSyncUnavailable;

    
This field is ignored by the SyncManager.

/**
     * 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 until a time in seconds since Java epoch.

For example, if you want to delay the next sync for at least 5 minutes, then:

result.delayUntil = (System.currentTimeMillis() / 1000) + 5 * 60;



By default, when a sync fails, the system retries later with an exponential back-off with the system default initial delay time, which always wins over delayUntil -- i.e. if the system back-off time is larger than delayUntil, delayUntil will essentially be ignored. 
/**
     * Used to indicate to the SyncManager that future sync requests that match the request's
     * Account and authority should be delayed until a time in seconds since Java epoch.
     *
     * <p>For example, if you want to delay the next sync for at least 5 minutes, then:
     * <pre>
     * result.delayUntil = (System.currentTimeMillis() / 1000) + 5 * 60;
     * </pre>
     *
     * <p>By default, when a sync fails, the system retries later with an exponential back-off
     * with the system default initial delay time, which always wins over {@link #delayUntil} --
     * i.e. if the system back-off time is larger than {@link #delayUntil}, {@link #delayUntil}
     * will essentially be ignored.
     */
    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.

/**
     * 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.

/**
     * 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.

 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 ContentResolver.SYNC_EXTRAS_UPLOAD request, in which the request is retryed without the ContentResolver.SYNC_EXTRAS_UPLOAD extra set). The SyncManager checks the type of error by calling hasHardError() and hasSoftError(). If both are true then the SyncManager treats it as a hard error, not a soft error. 
/**
     * 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.

Params:
/**
     * 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 SyncResult() for an explanation of what the SyncManager does when it sees a hard error. 

A hard error is indicated when any of the following is true:

Returns:true if a hard error is indicated
/**
     * 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 SyncResult() for an explanation of what the SyncManager does when it sees a soft error. 

A soft error is indicated when any of the following is true:



Returns:true if a soft error is indicated
/**
     * 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 soft error is indicated
     */
    public boolean hasSoftError() {
        return syncAlreadyInProgress || stats.numIoExceptions > 0;
    }

    
A convenience method for determining of the SyncResult indicates that an error occurred.

Returns:true if either a soft or hard error occurred
/**
     * 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();
    }

    
Convenience method for determining if the Sync should be rescheduled after failing for some
reason.

Returns:true if the SyncManager should reschedule this sync.
/**
     * Convenience method for determining if the Sync should be rescheduled after failing for some
     * reason.
     * @return true if the SyncManager should reschedule this sync.
     */
    public boolean madeSomeProgress() {
        return ((stats.numDeletes > 0) && !tooManyDeletions)
                || stats.numInserts > 0
                || stats.numUpdates > 0;
    }

    
Clears the SyncResult to a clean state. Throws an UnsupportedOperationException if this is called when syncAlreadyInProgress is set. 
/**
     * 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

Returns:debugging string.
/**
     * 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();
    }
}