SyncRequest.java revision 47d2b61ddb250eafbdd1eb43890f06ebab0d7057
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; 3556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams /** Don't allow this sync request on metered networks. */ 3656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams private final boolean mDisallowMetered; 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 * 8956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @return account object for this sync. 9056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @throws IllegalArgumentException if this function is called for a request that targets a 9156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * sync service. 92fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 9356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams public Account getAccount() { 94fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (!hasAuthority()) { 9556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("Cannot getAccount() for a sync that targets a sync" 9656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams + "service."); 97fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 9856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams return mAccountToSync; 9956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 10056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams 10156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams /** 10256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@hide} 10356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * 10456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @return provider for this sync. 10556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @throws IllegalArgumentException if this function is called for a request that targets a 10656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * sync service. 10756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams */ 10856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams public String getProvider() { 10956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (!hasAuthority()) { 11056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("Cannot getProvider() for a sync that targets a" 11156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams + "sync service."); 11256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 11356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams return mAuthority; 114fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 115fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 116fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 117fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 118fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Throws a runtime IllegalArgumentException if this function is called for a 119fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest that is bound to an account/provider. 120fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 121fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return ComponentName for the service that this sync will bind to. 122fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 123fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public ComponentName getService() { 124fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (hasAuthority()) { 125fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException( 126fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams "Cannot getAnonymousService() for a sync that has specified a provider."); 127fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 128fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mComponentInfo; 129fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 130fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 131fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 132fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 133fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Retrieve bundle for this SyncRequest. Will not be null. 134fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 135fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Bundle getBundle() { 136fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mExtras; 137fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 138fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 139fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 140fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 141fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the earliest point in time that this sync can be scheduled. 142fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 143fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncFlexTime() { 144fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncFlexTimeSecs; 145fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 146fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 147fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 148fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the last point in time at which this sync must scheduled. 149fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 150fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncRunTime() { 151fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncRunTimeSecs; 152fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 153fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 154fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static final Creator<SyncRequest> CREATOR = new Creator<SyncRequest>() { 155fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 156fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 157fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest createFromParcel(Parcel in) { 158fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(in); 159fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 160fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 161fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 162fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest[] newArray(int size) { 163fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest[size]; 164fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 165fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams }; 166fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 167fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 168fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public int describeContents() { 169fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return 0; 170fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 171fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 172fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 173fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public void writeToParcel(Parcel parcel, int flags) { 174fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeBundle(mExtras); 175fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncFlexTimeSecs); 176fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncRunTimeSecs); 177fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsPeriodic ? 1 : 0)); 17856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams parcel.writeInt((mDisallowMetered ? 1 : 0)); 179fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mTxBytes); 180fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mRxBytes); 181fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsAuthority ? 1 : 0)); 182fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsExpedited? 1 : 0)); 183fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsAuthority) { 184fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeParcelable(mAccountToSync, flags); 185fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeString(mAuthority); 186fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else { 187fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeParcelable(mComponentInfo, flags); 188fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 189fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 190fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 191fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private SyncRequest(Parcel in) { 192fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = in.readBundle(); 193fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = in.readLong(); 194fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = in.readLong(); 195fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (in.readInt() != 0); 19656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mDisallowMetered = (in.readInt() != 0); 197fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = in.readLong(); 198fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = in.readLong(); 199fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (in.readInt() != 0); 200fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = (in.readInt() != 0); 201fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsAuthority) { 202fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = null; 203fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = in.readParcelable(null); 204fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = in.readString(); 205fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else { 206fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = in.readParcelable(null); 207fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = null; 208fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = null; 209fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 210fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 211fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 212fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@hide} Protected ctor to instantiate anonymous SyncRequest. */ 213fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams protected SyncRequest(SyncRequest.Builder b) { 214fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = b.mSyncFlexTimeSecs; 215fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = b.mSyncRunTimeSecs; 216fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = b.mAccount; 217fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = b.mAuthority; 218fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentInfo = b.mComponentName; 219fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (b.mSyncType == Builder.SYNC_TYPE_PERIODIC); 220fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (b.mSyncTarget == Builder.SYNC_TARGET_ADAPTER); 221fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = b.mExpedited; 222fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = new Bundle(b.mCustomExtras); 22368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // For now we merge the sync config extras & the custom extras into one bundle. 22468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // TODO: pass the configuration extras through separately. 22568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mExtras.putAll(b.mSyncConfigExtras); 22656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mDisallowMetered = b.mDisallowMetered; 227fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = b.mTxBytes; 228fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = b.mRxBytes; 229fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 230fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 231fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 232fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Builder class for a @link SyncRequest. As you build your SyncRequest this class will also 233fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * perform validation. 234fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 235fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static class Builder { 236fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync type. */ 237fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_UNKNOWN = 0; 238fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a periodic sync. */ 239fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_PERIODIC = 1; 240fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a one-time sync. */ 241fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_ONCE = 2; 242fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync target. */ 243fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_UNKNOWN = 0; 244fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is an anonymous sync. */ 245fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_SERVICE = 1; 246fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a sync with a provider. */ 247fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_ADAPTER = 2; 248fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 249fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Earliest point of displacement into the future at which this sync can 250fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * occur. 251fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 252fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncFlexTimeSecs; 253fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Displacement into the future at which this sync must occur. */ 254fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncRunTimeSecs; 255fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 256fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync configuration information - custom user data explicitly provided by the developer. 257fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * This data is handed over to the sync operation. 258fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 259fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mCustomExtras; 260fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 261fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync system configuration - used to store system sync configuration. Corresponds to 262fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * ContentResolver.SYNC_EXTRAS_* flags. 263fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Use this instead of dumping into one bundle. Need to decide if these flags should 264fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * discriminate between equivalent syncs. 265fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 266fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mSyncConfigExtras; 267fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Expected upload transfer in bytes. */ 268fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mTxBytes = -1L; 269fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Expected download transfer in bytes. */ 270fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mRxBytes = -1L; 271fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether or not this sync can occur on metered networks. Default false. */ 27256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams private boolean mDisallowMetered; 273fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Priority of this sync relative to others from calling app [-2, 2]. Default 0. */ 274fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mPriority = 0; 275fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 276fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether this builder is building a periodic sync, or a one-time sync. 277fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 278fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncType = SYNC_TYPE_UNKNOWN; 279fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether this will go to a sync adapter or to a sync service. */ 280fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncTarget = SYNC_TARGET_UNKNOWN; 281fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether this is a user-activated sync. */ 282fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIsManual; 283fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 284fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to retry this one-time sync if the sync fails. Not valid for 285c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * periodic syncs. See {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 286fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 287fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mNoRetry; 288fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 289fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to respect back-off for this one-time sync. Not valid for 290fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * periodic syncs. See 291c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}; 292fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 293fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreBackoff; 294fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 295fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Ignore sync system settings and perform sync anyway. */ 296fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreSettings; 297fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 298fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** This sync will run in preference to other non-expedited syncs. */ 299fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mExpedited; 300fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 301fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 302c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * The {@link SyncService} component that 303fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * contains the sync logic if this is a provider-less sync, otherwise 304fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * null. 305fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 306fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private ComponentName mComponentName; 307fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 308fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Account object that together with an Authority name define the SyncAdapter (if 309c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 310fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 311fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Account mAccount; 312fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 313fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Authority name that together with an Account define the SyncAdapter (if 314c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 315fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 316fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private String mAuthority; 317fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 318fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder() { 319fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 320fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 321fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 32247d2b61ddb250eafbdd1eb43890f06ebab0d7057Nick Kralevich * Request that a sync occur immediately. 323fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 324fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example 325fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 32669002ae2a2afd0f759c22ea47d669ddc33b3255aNick Kralevich * SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce(); 327fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 328fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 32969002ae2a2afd0f759c22ea47d669ddc33b3255aNick Kralevich public Builder syncOnce() { 330fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 331fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 332fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 333fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_ONCE; 33469002ae2a2afd0f759c22ea47d669ddc33b3255aNick Kralevich setupInterval(0, 0); 335fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 336fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 337fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 338fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 339fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Build a periodic sync. Either this or syncOnce() <b>must</b> be called for this builder. 340fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Syncs are identified by target {@link SyncService}/{@link android.provider} and by the 341fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * contents of the extras bundle. 342fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * You cannot reuse the same builder for one-time syncs after having specified a periodic 343c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * sync (by calling this function). If you do, an <code>IllegalArgumentException</code> 344c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * will be thrown. 34556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * <p>The bundle for a periodic sync can be queried by applications with the correct 34656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * permissions using 34756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@link ContentResolver#getPeriodicSyncs(Account account, String provider)}, so no 34856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * sensitive data should be transferred here. 349c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 350fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example usage. 351fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 352fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 353fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Request a periodic sync every 5 hours with 20 minutes of flex. 354fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 355fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(5 * HOUR_IN_SECS, 20 * MIN_IN_SECS); 356fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 357fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Schedule a periodic sync every hour at any point in time during that hour. 358fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 359fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(1 * HOUR_IN_SECS, 1 * HOUR_IN_SECS); 360fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 361fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 362fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * N.B.: Periodic syncs are not allowed to have any of 3638cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}, 3648cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}, 3658cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}, 3668cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_INITIALIZE}, 3678cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_FORCE}, 3688cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_EXPEDITED}, 3698cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_MANUAL} 370c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * set to true. If any are supplied then an <code>IllegalArgumentException</code> will 371fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * be thrown. 372fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 373fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param pollFrequency the amount of time in seconds that you wish 374fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * to elapse between periodic syncs. 375fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param beforeSeconds the amount of flex time in seconds before 376fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@code pollFrequency} that you permit for the sync to take 377fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * place. Must be less than {@code pollFrequency}. 378fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 379fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder syncPeriodic(long pollFrequency, long beforeSeconds) { 380fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 381fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 382fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 383fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_PERIODIC; 384fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams setupInterval(pollFrequency, beforeSeconds); 385fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 386fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 387fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 388fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@hide} */ 389fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private void setupInterval(long at, long before) { 390fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (before > at) { 391fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Specified run time for the sync must be" + 392c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams " after the specified flex time."); 393fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 394fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = at; 395fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = before; 396fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 397fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 398fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 399c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Developer can provide insight into their payload size; optional. -1 specifies unknown, 400c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * so that you are not restricted to defining both fields. 401fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 402fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param rxBytes Bytes expected to be downloaded. 403fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param txBytes Bytes expected to be uploaded. 404fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 405fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setTransferSize(long rxBytes, long txBytes) { 406fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mRxBytes = rxBytes; 407fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mTxBytes = txBytes; 408fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 409fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 410fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 411fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 41256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * Will throw an <code>IllegalArgumentException</code> if called and 41356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@link #setIgnoreSettings(boolean ignoreSettings)} has already been called. 41456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @param disallow true to allow this transfer on metered networks. Default false. 41556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * 416fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 41756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams public Builder setDisallowMetered(boolean disallow) { 41856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mIgnoreSettings && disallow) { 41956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("setDisallowMetered(true) after having" 42056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams + "specified that settings are ignored."); 42156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 42256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mDisallowMetered = disallow; 423fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 424fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 425fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 426fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 427c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Specify an authority and account for this transfer. Cannot be used with 428c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #setSyncAdapter(ComponentName cname)}. 429fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 430fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param authority 431fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param account Account to sync. Can be null unless this is a periodic 432fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * sync, for which verification by the ContentResolver will 433fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * fail. If a sync is performed without an account, the 434fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 435fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setSyncAdapter(Account account, String authority) { 436fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget != SYNC_TARGET_UNKNOWN) { 437fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync target has already been defined."); 438fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 439632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams if (authority != null && authority.length() == 0) { 440632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams throw new IllegalArgumentException("Authority must be non-empty"); 441632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams } 442fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncTarget = SYNC_TARGET_ADAPTER; 443fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccount = account; 444fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = authority; 445fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentName = null; 446fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 447fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 448fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 449fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 450c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Specify the {@link SyncService} component for this sync. This is not validated until 451c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * sync time so providing an incorrect component name here will not fail. Cannot be used 452c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * with {@link #setSyncAdapter(Account account, String authority)}. 453fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 454fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param cname ComponentName to identify your Anonymous service 455fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 456fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setSyncAdapter(ComponentName cname) { 457fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget != SYNC_TARGET_UNKNOWN) { 458fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync target has already been defined."); 459fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 460fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncTarget = SYNC_TARGET_SERVICE; 461fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mComponentName = cname; 462fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccount = null; 463fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = null; 464fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 465fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 466fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 467fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 468fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Developer-provided extras handed back when sync actually occurs. This bundle is copied 469c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * into the SyncRequest returned by {@link #build()}. 470fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 471fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example: 472fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 473fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * String[] syncItems = {"dog", "cat", "frog", "child"}; 474fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 475fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * new SyncRequest.Builder() 476fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * .setSyncAdapter(dummyAccount, dummyProvider) 477fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * .syncOnce(5 * MINUTES_IN_SECS); 478fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 479fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * for (String syncData : syncItems) { 480fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Bundle extras = new Bundle(); 481fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * extras.setString("data", syncData); 482fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder.setExtras(extras); 483fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * ContentResolver.sync(builder.build()); // Each sync() request creates a unique sync. 484fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * } 485fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 486fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Only values of the following types may be used in the extras bundle: 487fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <ul> 488fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Integer</li> 489fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Long</li> 490fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Boolean</li> 491fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Float</li> 492fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Double</li> 493fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>String</li> 494fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Account</li> 495fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>null</li> 496fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </ul> 497fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * If any data is present in the bundle not of this type, build() will 498fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * throw a runtime exception. 499fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 500c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param bundle extras bundle to set. 501fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 502fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExtras(Bundle bundle) { 503fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = bundle; 504fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 505fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 506fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 507fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 508c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 509c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 510c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * A one-off sync operation that fails will be retried with exponential back-off unless 511c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this is set to false. Not valid for periodic sync and will throw an 512c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> in build(). 513fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 514c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param noRetry true to not retry a failed sync. Default false. 515fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 516c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams public Builder setNoRetry(boolean noRetry) { 517c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams mNoRetry = noRetry; 518fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 519fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 520fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 521fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 522c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}. 523c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 524c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 525c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 52656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * <p>Throws <code>IllegalArgumentException</code> if called and 52756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@link #setDisallowMetered(boolean)} has been set. 52856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * 529c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 530c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param ignoreSettings true to ignore the sync automatically settings. Default false. 531fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 532fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreSettings(boolean ignoreSettings) { 53356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mDisallowMetered && ignoreSettings) { 53456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("setIgnoreSettings(true) after having specified" 53556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams + " sync settings with this builder."); 53656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 537fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreSettings = ignoreSettings; 538fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 539fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 540fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 541fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 5428cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}. 543fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 544c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Ignoring back-off will force the sync scheduling process to ignore any back-off that was 545c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * the result of a failed sync, as well as to invalidate any {@link SyncResult#delayUntil} 546c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * value that may have been set by the adapter. Successive failures will not honor this 547c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * flag. Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> 548c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * in {@link #build()}. 549c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 550c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param ignoreBackoff ignore back off settings. Default false. 551fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 552fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreBackoff(boolean ignoreBackoff) { 553fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreBackoff = ignoreBackoff; 554fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 555fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 556fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 557fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 558c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_MANUAL}. 559c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 560c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 561c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 562c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 563c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param isManual User-initiated sync or not. Default false. 564fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 565fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setManual(boolean isManual) { 566fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsManual = isManual; 567fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 568fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 569fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 570fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 571c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * An expedited sync runs immediately and can preempt other non-expedited running syncs. 572c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 573c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 574c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 575c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 576c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param expedited whether to run expedited. Default false. 577fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 578fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExpedited(boolean expedited) { 579fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExpedited = expedited; 580fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 581fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 582fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 583fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 584c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param priority the priority of this request among all requests from the calling app. 585c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Range of [-2,2] similar to how this is done with notifications. 586fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 587fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setPriority(int priority) { 588fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (priority < -2 || priority > 2) { 589fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Priority must be within range [-2, 2]"); 590fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 591fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mPriority = priority; 592fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 593fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 594fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 595fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 596fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Performs validation over the request and throws the runtime exception 597c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> if this validation fails. 598fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 599fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return a SyncRequest with the information contained within this 600fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder. 601fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 602fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest build() { 603fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams // Validate the extras bundle 60468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams ContentResolver.validateSyncExtrasBundle(mCustomExtras); 605fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mCustomExtras == null) { 606fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = new Bundle(); 607fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 60868e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // Combine builder extra flags into the config bundle. 60968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras = new Bundle(); 610fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreBackoff) { 61168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, true); 612fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 61356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mDisallowMetered) { 61456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_DISALLOW_METERED, true); 615fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 616fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreSettings) { 61768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, true); 618fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 619fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mNoRetry) { 62068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY, true); 621fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 622fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mExpedited) { 62368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_EXPEDITED, true); 624fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 625fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsManual) { 62656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, true); 62756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, true); 628fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 62968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putLong(ContentResolver.SYNC_EXTRAS_EXPECTED_UPLOAD, mTxBytes); 63068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putLong(ContentResolver.SYNC_EXTRAS_EXPECTED_DOWNLOAD, mRxBytes); 63168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putInt(ContentResolver.SYNC_EXTRAS_PRIORITY, mPriority); 632fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType == SYNC_TYPE_PERIODIC) { 63368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // If this is a periodic sync ensure than invalid extras were not set. 63456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (ContentResolver.invalidPeriodicExtras(mCustomExtras) || 63556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams ContentResolver.invalidPeriodicExtras(mSyncConfigExtras)) { 63656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("Illegal extras were set"); 63756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 638fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } else if (mSyncType == SYNC_TYPE_UNKNOWN) { 639fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Must call either syncOnce() or syncPeriodic()"); 640fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 64156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mSyncTarget == SYNC_TARGET_SERVICE) { 64256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mSyncConfigExtras.getBoolean(ContentResolver.SYNC_EXTRAS_INITIALIZE, false)) { 64356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("Cannot specify an initialisation sync" 64456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams + " that targets a service."); 64556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 64656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 647fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams // Ensure that a target for the sync has been set. 648fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget == SYNC_TARGET_UNKNOWN) { 649fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Must specify an adapter with one of" 650fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams + "setSyncAdapter(ComponentName) or setSyncAdapter(Account, String"); 651fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 652fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(this); 653fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 65456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 655fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams} 656