SyncRequest.java revision 68e39c3411d97ba2fe3ef5e33260b31fc73c934f
1fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams/* 2fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Copyright (C) 2013 The Android Open Source Project 3fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 4fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Licensed under the Apache License, Version 2.0 (the "License"); 5fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * you may not use this file except in compliance with the License. 6fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * You may obtain a copy of the License at 7fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 8fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * http://www.apache.org/licenses/LICENSE-2.0 9fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 10fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Unless required by applicable law or agreed to in writing, software 11fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * distributed under the License is distributed on an "AS IS" BASIS, 12fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * See the License for the specific language governing permissions and 14fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * limitations under the License. 15fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 16fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 17fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamspackage android.content; 18fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 19fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.accounts.Account; 20fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.os.Bundle; 21fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.os.Parcel; 22fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.os.Parcelable; 23fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamsimport android.util.Pair; 24fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 25fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamspublic class SyncRequest implements Parcelable { 26fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final String TAG = "SyncRequest"; 27fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Account to pass to the sync adapter. Can be null. */ 28fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final Account mAccountToSync; 29fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Authority string that corresponds to a ContentProvider. */ 30fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final String mAuthority; 31fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@link SyncService} identifier. */ 32fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final ComponentName mComponentInfo; 33fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Bundle containing user info as well as sync settings. */ 34fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final Bundle mExtras; 35fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Allow this sync request on metered networks. */ 36fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mAllowMetered; 37fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 38fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Anticipated upload size in bytes. 39fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Not yet used - we put this information into the bundle for simplicity. 40fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 41fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mTxBytes; 42fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 43fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Anticipated download size in bytes. 44fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Not yet used - we put this information into the bundle. 45fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 46fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mRxBytes; 47fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 48c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Amount of time before {@link #mSyncRunTimeSecs} from which the sync may optionally be 49fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * started. 50fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 51fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mSyncFlexTimeSecs; 52fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 53fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Specifies a point in the future at which the sync must have been scheduled to run. 54fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 55fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mSyncRunTimeSecs; 56fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Periodic versus one-off. */ 57fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsPeriodic; 58fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Service versus provider. */ 59fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsAuthority; 60fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Sync should be run in lieu of other syncs. */ 61fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsExpedited; 62fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 63fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 64fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 65fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return whether this sync is periodic or one-time. A Sync Request must be 66fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * either one of these or an InvalidStateException will be thrown in 67fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Builder.build(). 68fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 69fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean isPeriodic() { 70fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsPeriodic; 71fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 72fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 73fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean isExpedited() { 74fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsExpedited; 75fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 76fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 77fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 78fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 79fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return true if this sync uses an account/authority pair, or false if 80fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * this is an anonymous sync bound to an @link AnonymousSyncService. 81fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 82fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean hasAuthority() { 83fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsAuthority; 84fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 85fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 86fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 87fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 88fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Throws a runtime IllegalArgumentException if this function is called for an 89fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * anonymous sync. 90fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 91fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return (Account, Provider) for this SyncRequest. 92fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 93fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Pair<Account, String> getProviderInfo() { 94fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (!hasAuthority()) { 95fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Cannot getProviderInfo() for an anonymous sync."); 96fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 97fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return Pair.create(mAccountToSync, mAuthority); 98fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 99fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 100fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 101fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 102fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Throws a runtime IllegalArgumentException if this function is called for a 103fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest that is bound to an account/provider. 104fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 105fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return ComponentName for the service that this sync will bind to. 106fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 107fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public ComponentName getService() { 108fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (hasAuthority()) { 109fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException( 110fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams "Cannot getAnonymousService() for a sync that has specified a provider."); 111fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 112fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mComponentInfo; 113fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 114fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 115fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 116fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 117fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Retrieve bundle for this SyncRequest. Will not be null. 118fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 119fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Bundle getBundle() { 120fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mExtras; 121fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 122fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 123fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 124fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 125fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the earliest point in time that this sync can be scheduled. 126fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 127fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncFlexTime() { 128fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncFlexTimeSecs; 129fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 130fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 131fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 132fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the last point in time at which this sync must scheduled. 133fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 134fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncRunTime() { 135fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncRunTimeSecs; 136fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 137fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 138fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static final Creator<SyncRequest> CREATOR = new Creator<SyncRequest>() { 139fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 140fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 141fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest createFromParcel(Parcel in) { 142fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(in); 143fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 144fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 145fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 146fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest[] newArray(int size) { 147fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest[size]; 148fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 149fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams }; 150fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 151fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 152fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public int describeContents() { 153fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return 0; 154fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 155fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 156fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 157fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public void writeToParcel(Parcel parcel, int flags) { 158fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeBundle(mExtras); 159fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncFlexTimeSecs); 160fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncRunTimeSecs); 161fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsPeriodic ? 1 : 0)); 162fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mAllowMetered ? 1 : 0)); 163fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mTxBytes); 164fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mRxBytes); 165fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsAuthority ? 1 : 0)); 166fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsExpedited? 1 : 0)); 167fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsAuthority) { 168fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeParcelable(mAccountToSync, flags); 169fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeString(mAuthority); 170fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else { 171fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeParcelable(mComponentInfo, flags); 172fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 173fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 174fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 175fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private SyncRequest(Parcel in) { 176fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = in.readBundle(); 177fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = in.readLong(); 178fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = in.readLong(); 179fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (in.readInt() != 0); 180fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAllowMetered = (in.readInt() != 0); 181fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = in.readLong(); 182fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = in.readLong(); 183fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (in.readInt() != 0); 184fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = (in.readInt() != 0); 185fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsAuthority) { 186fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = null; 187fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = in.readParcelable(null); 188fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = in.readString(); 189fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else { 190fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = in.readParcelable(null); 191fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = null; 192fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = null; 193fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 194fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 195fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 196fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@hide} Protected ctor to instantiate anonymous SyncRequest. */ 197fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams protected SyncRequest(SyncRequest.Builder b) { 198fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = b.mSyncFlexTimeSecs; 199fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = b.mSyncRunTimeSecs; 200fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = b.mAccount; 201fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = b.mAuthority; 202fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = b.mComponentName; 203fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (b.mSyncType == Builder.SYNC_TYPE_PERIODIC); 204fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (b.mSyncTarget == Builder.SYNC_TARGET_ADAPTER); 205fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = b.mExpedited; 206fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = new Bundle(b.mCustomExtras); 20768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // For now we merge the sync config extras & the custom extras into one bundle. 20868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // TODO: pass the configuration extras through separately. 20968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mExtras.putAll(b.mSyncConfigExtras); 210fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAllowMetered = b.mAllowMetered; 211fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = b.mTxBytes; 212fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = b.mRxBytes; 213fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 214fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 215fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 216fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Builder class for a @link SyncRequest. As you build your SyncRequest this class will also 217fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * perform validation. 218fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 219fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static class Builder { 220fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync type. */ 221fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_UNKNOWN = 0; 222fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a periodic sync. */ 223fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_PERIODIC = 1; 224fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a one-time sync. */ 225fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_ONCE = 2; 226fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync target. */ 227fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_UNKNOWN = 0; 228fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is an anonymous sync. */ 229fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_SERVICE = 1; 230fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a sync with a provider. */ 231fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_ADAPTER = 2; 232fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 233fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Earliest point of displacement into the future at which this sync can 234fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * occur. 235fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 236fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncFlexTimeSecs; 237fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Displacement into the future at which this sync must occur. */ 238fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncRunTimeSecs; 239fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 240fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync configuration information - custom user data explicitly provided by the developer. 241fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * This data is handed over to the sync operation. 242fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 243fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mCustomExtras; 244fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 245fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync system configuration - used to store system sync configuration. Corresponds to 246fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * ContentResolver.SYNC_EXTRAS_* flags. 247fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Use this instead of dumping into one bundle. Need to decide if these flags should 248fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * discriminate between equivalent syncs. 249fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 250fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mSyncConfigExtras; 251fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Expected upload transfer in bytes. */ 252fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mTxBytes = -1L; 253fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Expected download transfer in bytes. */ 254fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mRxBytes = -1L; 255fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether or not this sync can occur on metered networks. Default false. */ 256fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mAllowMetered; 257fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Priority of this sync relative to others from calling app [-2, 2]. Default 0. */ 258fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mPriority = 0; 259fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 260fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether this builder is building a periodic sync, or a one-time sync. 261fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 262fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncType = SYNC_TYPE_UNKNOWN; 263fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether this will go to a sync adapter or to a sync service. */ 264fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncTarget = SYNC_TARGET_UNKNOWN; 265fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether this is a user-activated sync. */ 266fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIsManual; 267fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 268fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to retry this one-time sync if the sync fails. Not valid for 269c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * periodic syncs. See {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 270fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 271fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mNoRetry; 272fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 273fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to respect back-off for this one-time sync. Not valid for 274fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * periodic syncs. See 275c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}; 276fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 277fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreBackoff; 278fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 279fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Ignore sync system settings and perform sync anyway. */ 280fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreSettings; 281fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 282fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** This sync will run in preference to other non-expedited syncs. */ 283fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mExpedited; 284fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 285fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 286c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * The {@link SyncService} component that 287fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * contains the sync logic if this is a provider-less sync, otherwise 288fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * null. 289fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 290fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private ComponentName mComponentName; 291fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 292fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Account object that together with an Authority name define the SyncAdapter (if 293c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 294fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 295fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Account mAccount; 296fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 297fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Authority name that together with an Account define the SyncAdapter (if 298c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 299fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 300fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private String mAuthority; 301fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 302fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder() { 303fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 304fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 305fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 306fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Developer can define timing constraints for this one-shot request. 307fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * These values are elapsed real-time. 308fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 309fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param whenSeconds The time in seconds at which you want this 310fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * sync to occur. 311fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param beforeSeconds The amount of time in advance of whenSeconds that this 312fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * sync may be permitted to occur. This is rounded up to a minimum of 5 313fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * seconds, for any sync for which whenSeconds > 5. 314fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 315fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example 316fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 317fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Perform an immediate sync. 318fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce(0, 0); 319fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * That is, a sync 0 seconds from now with 0 seconds of flex. 320fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 321fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Perform a sync in exactly 5 minutes. 322fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 323fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * new SyncRequest.Builder().syncOnce(5 * MIN_IN_SECS, 0); 324fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 325fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Perform a sync in 5 minutes, with one minute of leeway (between 4 and 5 minutes from 326fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * now). 327fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 328fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * new SyncRequest.Builder().syncOnce(5 * MIN_IN_SECS, 1 * MIN_IN_SECS); 329fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 330fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 331fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder syncOnce(long whenSeconds, long beforeSeconds) { 332fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 333fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 334fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 335fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_ONCE; 336fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams setupInterval(whenSeconds, beforeSeconds); 337fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 338fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 339fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 340fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 341fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Build a periodic sync. Either this or syncOnce() <b>must</b> be called for this builder. 342fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Syncs are identified by target {@link SyncService}/{@link android.provider} and by the 343fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * contents of the extras bundle. 344fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * You cannot reuse the same builder for one-time syncs after having specified a periodic 345c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * sync (by calling this function). If you do, an <code>IllegalArgumentException</code> 346c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * will be thrown. 347c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 348fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example usage. 349fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 350fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 351fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Request a periodic sync every 5 hours with 20 minutes of flex. 352fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 353fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(5 * HOUR_IN_SECS, 20 * MIN_IN_SECS); 354fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 355fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Schedule a periodic sync every hour at any point in time during that hour. 356fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 357fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(1 * HOUR_IN_SECS, 1 * HOUR_IN_SECS); 358fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 359fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 360fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * N.B.: Periodic syncs are not allowed to have any of 3618cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}, 3628cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}, 3638cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}, 3648cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_INITIALIZE}, 3658cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_FORCE}, 3668cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_EXPEDITED}, 3678cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_MANUAL} 368c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * set to true. If any are supplied then an <code>IllegalArgumentException</code> will 369fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * be thrown. 370fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 371fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param pollFrequency the amount of time in seconds that you wish 372fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * to elapse between periodic syncs. 373fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param beforeSeconds the amount of flex time in seconds before 374fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@code pollFrequency} that you permit for the sync to take 375fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * place. Must be less than {@code pollFrequency}. 376fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 377fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder syncPeriodic(long pollFrequency, long beforeSeconds) { 378fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 379fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 380fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 381fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_PERIODIC; 382fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams setupInterval(pollFrequency, beforeSeconds); 383fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 384fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 385fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 386fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@hide} */ 387fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private void setupInterval(long at, long before) { 388fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (before > at) { 389fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Specified run time for the sync must be" + 390c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams " after the specified flex time."); 391fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 392fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = at; 393fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = before; 394fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 395fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 396fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 397c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Developer can provide insight into their payload size; optional. -1 specifies unknown, 398c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * so that you are not restricted to defining both fields. 399fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 400fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param rxBytes Bytes expected to be downloaded. 401fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param txBytes Bytes expected to be uploaded. 402fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 403fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setTransferSize(long rxBytes, long txBytes) { 404fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = rxBytes; 405fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = txBytes; 406fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 407fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 408fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 409fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 410c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param allow false to allow this transfer on metered networks. Default true. 411fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 412fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setAllowMetered(boolean allow) { 413fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAllowMetered = true; 414fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 415fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 416fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 417fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 418c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Specify an authority and account for this transfer. Cannot be used with 419c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #setSyncAdapter(ComponentName cname)}. 420fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 421fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param authority 422fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param account Account to sync. Can be null unless this is a periodic 423fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * sync, for which verification by the ContentResolver will 424fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * fail. If a sync is performed without an account, the 425fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 426fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setSyncAdapter(Account account, String authority) { 427fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget != SYNC_TARGET_UNKNOWN) { 428fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync target has already been defined."); 429fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 430fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncTarget = SYNC_TARGET_ADAPTER; 431fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccount = account; 432fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = authority; 433fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentName = null; 434fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 435fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 436fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 437fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 438c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Specify the {@link SyncService} component for this sync. This is not validated until 439c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * sync time so providing an incorrect component name here will not fail. Cannot be used 440c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * with {@link #setSyncAdapter(Account account, String authority)}. 441fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 442fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param cname ComponentName to identify your Anonymous service 443fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 444fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setSyncAdapter(ComponentName cname) { 445fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget != SYNC_TARGET_UNKNOWN) { 446fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync target has already been defined."); 447fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 448fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncTarget = SYNC_TARGET_SERVICE; 449fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentName = cname; 450fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccount = null; 451fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = null; 452fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 453fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 454fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 455fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 456fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Developer-provided extras handed back when sync actually occurs. This bundle is copied 457c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * into the SyncRequest returned by {@link #build()}. 458fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 459fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example: 460fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 461fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * String[] syncItems = {"dog", "cat", "frog", "child"}; 462fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 463fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * new SyncRequest.Builder() 464fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * .setSyncAdapter(dummyAccount, dummyProvider) 465fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * .syncOnce(5 * MINUTES_IN_SECS); 466fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 467fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * for (String syncData : syncItems) { 468fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Bundle extras = new Bundle(); 469fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * extras.setString("data", syncData); 470fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder.setExtras(extras); 471fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * ContentResolver.sync(builder.build()); // Each sync() request creates a unique sync. 472fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * } 473fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 474fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Only values of the following types may be used in the extras bundle: 475fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <ul> 476fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Integer</li> 477fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Long</li> 478fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Boolean</li> 479fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Float</li> 480fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Double</li> 481fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>String</li> 482fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Account</li> 483fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>null</li> 484fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </ul> 485fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * If any data is present in the bundle not of this type, build() will 486fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * throw a runtime exception. 487fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 488c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param bundle extras bundle to set. 489fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 490fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExtras(Bundle bundle) { 491fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = bundle; 492fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 493fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 494fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 495fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 496c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 497c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 498c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * A one-off sync operation that fails will be retried with exponential back-off unless 499c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this is set to false. Not valid for periodic sync and will throw an 500c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> in build(). 501fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 502c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param noRetry true to not retry a failed sync. Default false. 503fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 504c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams public Builder setNoRetry(boolean noRetry) { 505c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams mNoRetry = noRetry; 506fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 507fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 508fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 509fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 510c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}. 511c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 512c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 513c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 514c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 515c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param ignoreSettings true to ignore the sync automatically settings. Default false. 516fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 517fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreSettings(boolean ignoreSettings) { 518fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreSettings = ignoreSettings; 519fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 520fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 521fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 522fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 5238cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}. 524fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 525c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Ignoring back-off will force the sync scheduling process to ignore any back-off that was 526c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * the result of a failed sync, as well as to invalidate any {@link SyncResult#delayUntil} 527c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * value that may have been set by the adapter. Successive failures will not honor this 528c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * flag. Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> 529c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * in {@link #build()}. 530c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 531c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param ignoreBackoff ignore back off settings. Default false. 532fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 533fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreBackoff(boolean ignoreBackoff) { 534fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreBackoff = ignoreBackoff; 535fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 536fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 537fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 538fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 539c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_MANUAL}. 540c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 541c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 542c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 543c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 544c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param isManual User-initiated sync or not. Default false. 545fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 546fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setManual(boolean isManual) { 547fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsManual = isManual; 548fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 549fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 550fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 551fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 552c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * An expedited sync runs immediately and can preempt other non-expedited running syncs. 553c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 554c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 555c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 556c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 557c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param expedited whether to run expedited. Default false. 558fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 559fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExpedited(boolean expedited) { 560fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExpedited = expedited; 561fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 562fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 563fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 564fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 565c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param priority the priority of this request among all requests from the calling app. 566c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Range of [-2,2] similar to how this is done with notifications. 567fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 568fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setPriority(int priority) { 569fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (priority < -2 || priority > 2) { 570fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Priority must be within range [-2, 2]"); 571fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 572fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mPriority = priority; 573fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 574fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 575fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 576fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 577fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Performs validation over the request and throws the runtime exception 578c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> if this validation fails. 579fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 580fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return a SyncRequest with the information contained within this 581fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder. 582fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 583fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest build() { 584fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams // Validate the extras bundle 58568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams ContentResolver.validateSyncExtrasBundle(mCustomExtras); 586fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mCustomExtras == null) { 587fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = new Bundle(); 588fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 58968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // Combine builder extra flags into the config bundle. 59068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras = new Bundle(); 591fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreBackoff) { 59268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, true); 593fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 594fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mAllowMetered) { 59568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_ALLOW_METERED, true); 596fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 597fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreSettings) { 59868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, true); 599fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 600fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mNoRetry) { 60168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY, true); 602fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 603fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mExpedited) { 60468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_EXPEDITED, true); 605fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 606fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsManual) { 60768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_MANUAL, true); 608fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 60968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putLong(ContentResolver.SYNC_EXTRAS_EXPECTED_UPLOAD, mTxBytes); 61068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putLong(ContentResolver.SYNC_EXTRAS_EXPECTED_DOWNLOAD, mRxBytes); 61168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putInt(ContentResolver.SYNC_EXTRAS_PRIORITY, mPriority); 612fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType == SYNC_TYPE_PERIODIC) { 61368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // If this is a periodic sync ensure than invalid extras were not set. 61468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams validatePeriodicExtras(mCustomExtras); 61568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams validatePeriodicExtras(mSyncConfigExtras); 616fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else if (mSyncType == SYNC_TYPE_UNKNOWN) { 617fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Must call either syncOnce() or syncPeriodic()"); 618fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 619fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams // Ensure that a target for the sync has been set. 620fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget == SYNC_TARGET_UNKNOWN) { 621fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Must specify an adapter with one of" 622fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams + "setSyncAdapter(ComponentName) or setSyncAdapter(Account, String"); 623fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 624fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(this); 625fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 62668e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams 62768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams /** 62868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * Helper function to throw an <code>IllegalArgumentException</code> if any illegal 62968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * extras were set for a periodic sync. 63068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * 63168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams * @param extras bundle to validate. 63268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams */ 63368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams private void validatePeriodicExtras(Bundle extras) { 63468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams if (extras.getBoolean(ContentResolver.SYNC_EXTRAS_MANUAL, false) 63568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY, false) 63668e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, false) 63768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, false) 63868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_INITIALIZE, false) 63968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_FORCE, false) 64068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams || extras.getBoolean(ContentResolver.SYNC_EXTRAS_EXPEDITED, false)) { 64168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams throw new IllegalArgumentException("Illegal extras were set"); 64268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams } 64368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams } 644fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 645fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams} 646