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 Williams 242368014073a7614820284f38025d926fd1699085Matthew Williams/** 252368014073a7614820284f38025d926fd1699085Matthew Williams * Convenience class to construct sync requests. See {@link android.content.SyncRequest.Builder} 262368014073a7614820284f38025d926fd1699085Matthew Williams * for an explanation of the various functions. The resulting object is passed through to the 272368014073a7614820284f38025d926fd1699085Matthew Williams * framework via {@link android.content.ContentResolver#requestSync(SyncRequest)}. 282368014073a7614820284f38025d926fd1699085Matthew Williams */ 29fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williamspublic class SyncRequest implements Parcelable { 30fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final String TAG = "SyncRequest"; 31fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Account to pass to the sync adapter. Can be null. */ 32fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final Account mAccountToSync; 33fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Authority string that corresponds to a ContentProvider. */ 34fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final String mAuthority; 35fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Bundle containing user info as well as sync settings. */ 36fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final Bundle mExtras; 3756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams /** Don't allow this sync request on metered networks. */ 3856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams private final boolean mDisallowMetered; 39fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 40c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Amount of time before {@link #mSyncRunTimeSecs} from which the sync may optionally be 41fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * started. 42fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 43fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mSyncFlexTimeSecs; 44fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 45fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Specifies a point in the future at which the sync must have been scheduled to run. 46fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 47fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final long mSyncRunTimeSecs; 48fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Periodic versus one-off. */ 49fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsPeriodic; 50fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Service versus provider. */ 51fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsAuthority; 52fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Sync should be run in lieu of other syncs. */ 53fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private final boolean mIsExpedited; 54fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 55fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 56fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 57fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return whether this sync is periodic or one-time. A Sync Request must be 58fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * either one of these or an InvalidStateException will be thrown in 59fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Builder.build(). 60fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 61fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean isPeriodic() { 62fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsPeriodic; 63fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 64fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 652368014073a7614820284f38025d926fd1699085Matthew Williams /** 662368014073a7614820284f38025d926fd1699085Matthew Williams * {@hide} 672368014073a7614820284f38025d926fd1699085Matthew Williams * @return whether this sync is expedited. 682368014073a7614820284f38025d926fd1699085Matthew Williams */ 69fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public boolean isExpedited() { 70fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mIsExpedited; 71fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 72fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 73fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 74fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 75fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 7656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @return account object for this sync. 7756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @throws IllegalArgumentException if this function is called for a request that targets a 7856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * sync service. 79fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 8056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams public Account getAccount() { 8156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams return mAccountToSync; 8256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 8356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams 8456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams /** 8556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@hide} 8656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * 8756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @return provider for this sync. 8856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @throws IllegalArgumentException if this function is called for a request that targets a 8956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * sync service. 9056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams */ 9156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams public String getProvider() { 9256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams return mAuthority; 93fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 94fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 95fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 96fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 97fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Retrieve bundle for this SyncRequest. Will not be null. 98fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 99fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Bundle getBundle() { 100fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mExtras; 101fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 102fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 103fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 104fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 105fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the earliest point in time that this sync can be scheduled. 106fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 107fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncFlexTime() { 108fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncFlexTimeSecs; 109fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 110fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 111fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@hide} 112fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return the last point in time at which this sync must scheduled. 113fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 114fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public long getSyncRunTime() { 115fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return mSyncRunTimeSecs; 116fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 117fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 118fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static final Creator<SyncRequest> CREATOR = new Creator<SyncRequest>() { 119fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 120fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 121fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest createFromParcel(Parcel in) { 122fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(in); 123fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 124fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 125fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 126fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest[] newArray(int size) { 127fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest[size]; 128fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 129fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams }; 130fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 131fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 132fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public int describeContents() { 133fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return 0; 134fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 135fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 136fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams @Override 137fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public void writeToParcel(Parcel parcel, int flags) { 138fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeBundle(mExtras); 139fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncFlexTimeSecs); 140fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeLong(mSyncRunTimeSecs); 141fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsPeriodic ? 1 : 0)); 14256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams parcel.writeInt((mDisallowMetered ? 1 : 0)); 143fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsAuthority ? 1 : 0)); 144fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams parcel.writeInt((mIsExpedited? 1 : 0)); 14564939ae385edf615ac2912060df5624dbaf57cabMatthew Williams parcel.writeParcelable(mAccountToSync, flags); 14664939ae385edf615ac2912060df5624dbaf57cabMatthew Williams parcel.writeString(mAuthority); 147fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 148fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 149fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private SyncRequest(Parcel in) { 150fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = in.readBundle(); 151fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = in.readLong(); 152fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = in.readLong(); 153fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (in.readInt() != 0); 15456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mDisallowMetered = (in.readInt() != 0); 155fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (in.readInt() != 0); 156fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = (in.readInt() != 0); 15764939ae385edf615ac2912060df5624dbaf57cabMatthew Williams mAccountToSync = in.readParcelable(null); 15864939ae385edf615ac2912060df5624dbaf57cabMatthew Williams mAuthority = in.readString(); 159fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 160fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 161fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** {@hide} Protected ctor to instantiate anonymous SyncRequest. */ 162fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams protected SyncRequest(SyncRequest.Builder b) { 163fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = b.mSyncFlexTimeSecs; 164fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = b.mSyncRunTimeSecs; 165fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccountToSync = b.mAccount; 166fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = b.mAuthority; 167fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsPeriodic = (b.mSyncType == Builder.SYNC_TYPE_PERIODIC); 168fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsAuthority = (b.mSyncTarget == Builder.SYNC_TARGET_ADAPTER); 169fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsExpedited = b.mExpedited; 170fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExtras = new Bundle(b.mCustomExtras); 17168e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // For now we merge the sync config extras & the custom extras into one bundle. 17268e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // TODO: pass the configuration extras through separately. 17368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mExtras.putAll(b.mSyncConfigExtras); 17456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mDisallowMetered = b.mDisallowMetered; 175fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 176fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 177fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 178fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Builder class for a @link SyncRequest. As you build your SyncRequest this class will also 179fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * perform validation. 180fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 181fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public static class Builder { 182fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync type. */ 183fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_UNKNOWN = 0; 184fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a periodic sync. */ 185fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_PERIODIC = 1; 186fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a one-time sync. */ 187fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TYPE_ONCE = 2; 188fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Unknown sync target. */ 189fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_UNKNOWN = 0; 190fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Specify that this is a sync with a provider. */ 191fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private static final int SYNC_TARGET_ADAPTER = 2; 192fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 193fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Earliest point of displacement into the future at which this sync can 194fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * occur. 195fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 196fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncFlexTimeSecs; 197fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Displacement into the future at which this sync must occur. */ 198fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private long mSyncRunTimeSecs; 199fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 200fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync configuration information - custom user data explicitly provided by the developer. 201fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * This data is handed over to the sync operation. 202fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 203fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mCustomExtras; 204fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 205fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Sync system configuration - used to store system sync configuration. Corresponds to 206fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * ContentResolver.SYNC_EXTRAS_* flags. 207fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * TODO: Use this instead of dumping into one bundle. Need to decide if these flags should 208fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * discriminate between equivalent syncs. 209fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 210fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Bundle mSyncConfigExtras; 211fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether or not this sync can occur on metered networks. Default false. */ 21256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams private boolean mDisallowMetered; 213fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 214fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether this builder is building a periodic sync, or a one-time sync. 215fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 216fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncType = SYNC_TYPE_UNKNOWN; 21764939ae385edf615ac2912060df5624dbaf57cabMatthew Williams /** Whether this will go to a sync adapter. */ 218fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private int mSyncTarget = SYNC_TARGET_UNKNOWN; 219fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Whether this is a user-activated sync. */ 220fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIsManual; 221fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 222fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to retry this one-time sync if the sync fails. Not valid for 223c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * periodic syncs. See {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 224fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 225fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mNoRetry; 226fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 227fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Whether to respect back-off for this one-time sync. Not valid for 228fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * periodic syncs. See 229c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}; 230fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 231fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreBackoff; 232fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 233fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** Ignore sync system settings and perform sync anyway. */ 234fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mIgnoreSettings; 235fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 236fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** This sync will run in preference to other non-expedited syncs. */ 237fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private boolean mExpedited; 238fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 239fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 240fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Account object that together with an Authority name define the SyncAdapter (if 241c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 242fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 243fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private Account mAccount; 244fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 245fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * The Authority name that together with an Account define the SyncAdapter (if 246c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this sync is bound to a provider), otherwise null. 247fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 248fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private String mAuthority; 249fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 250fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder() { 251fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 252fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 253fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 25447d2b61ddb250eafbdd1eb43890f06ebab0d7057Nick Kralevich * Request that a sync occur immediately. 255fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 256fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example 257fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 25869002ae2a2afd0f759c22ea47d669ddc33b3255aNick Kralevich * SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce(); 259fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 260fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 26169002ae2a2afd0f759c22ea47d669ddc33b3255aNick Kralevich public Builder syncOnce() { 262fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 263fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 264fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 265fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_ONCE; 26669002ae2a2afd0f759c22ea47d669ddc33b3255aNick Kralevich setupInterval(0, 0); 267fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 268fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 269fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 270fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 271fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Build a periodic sync. Either this or syncOnce() <b>must</b> be called for this builder. 27264939ae385edf615ac2912060df5624dbaf57cabMatthew Williams * Syncs are identified by target {@link android.provider} and by the 273fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * contents of the extras bundle. 274fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * You cannot reuse the same builder for one-time syncs after having specified a periodic 275c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * sync (by calling this function). If you do, an <code>IllegalArgumentException</code> 276c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * will be thrown. 27756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * <p>The bundle for a periodic sync can be queried by applications with the correct 27856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * permissions using 27956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@link ContentResolver#getPeriodicSyncs(Account account, String provider)}, so no 28056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * sensitive data should be transferred here. 281c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 282fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example usage. 283fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 284fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 285fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Request a periodic sync every 5 hours with 20 minutes of flex. 286fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 287fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(5 * HOUR_IN_SECS, 20 * MIN_IN_SECS); 288fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 289fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Schedule a periodic sync every hour at any point in time during that hour. 290fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 291fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * (new SyncRequest.Builder()).syncPeriodic(1 * HOUR_IN_SECS, 1 * HOUR_IN_SECS); 292fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 293fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 294fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * N.B.: Periodic syncs are not allowed to have any of 2958cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}, 2968cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}, 2978cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}, 2988cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_INITIALIZE}, 2998cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_FORCE}, 3008cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_EXPEDITED}, 3018cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * {@link ContentResolver#SYNC_EXTRAS_MANUAL} 302c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * set to true. If any are supplied then an <code>IllegalArgumentException</code> will 303fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * be thrown. 304fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 305fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param pollFrequency the amount of time in seconds that you wish 306fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * to elapse between periodic syncs. 307fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param beforeSeconds the amount of flex time in seconds before 308fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * {@code pollFrequency} that you permit for the sync to take 309fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * place. Must be less than {@code pollFrequency}. 310fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 311fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder syncPeriodic(long pollFrequency, long beforeSeconds) { 312fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType != SYNC_TYPE_UNKNOWN) { 313fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync type has already been defined."); 314fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 315fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncType = SYNC_TYPE_PERIODIC; 316fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams setupInterval(pollFrequency, beforeSeconds); 317fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 318fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 319fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 320fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams private void setupInterval(long at, long before) { 321fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (before > at) { 322fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Specified run time for the sync must be" + 323c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams " after the specified flex time."); 324fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 325fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncRunTimeSecs = at; 326fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncFlexTimeSecs = before; 327fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 328fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 329fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 33056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * Will throw an <code>IllegalArgumentException</code> if called and 33156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@link #setIgnoreSettings(boolean ignoreSettings)} has already been called. 33256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * @param disallow true to allow this transfer on metered networks. Default false. 33364939ae385edf615ac2912060df5624dbaf57cabMatthew Williams * 334fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 33556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams public Builder setDisallowMetered(boolean disallow) { 33656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mIgnoreSettings && disallow) { 33756dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("setDisallowMetered(true) after having" 33856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams + "specified that settings are ignored."); 33956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 34056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mDisallowMetered = disallow; 341fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 342fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 343fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 344fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 34564939ae385edf615ac2912060df5624dbaf57cabMatthew Williams * Specify an authority and account for this transfer. 346fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 34764939ae385edf615ac2912060df5624dbaf57cabMatthew Williams * @param authority A String identifying the content provider to be synced. 348fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @param account Account to sync. Can be null unless this is a periodic 349fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * sync, for which verification by the ContentResolver will 350fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * fail. If a sync is performed without an account, the 351fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 352fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setSyncAdapter(Account account, String authority) { 353fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget != SYNC_TARGET_UNKNOWN) { 354fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams throw new IllegalArgumentException("Sync target has already been defined."); 355fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 356632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams if (authority != null && authority.length() == 0) { 357632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams throw new IllegalArgumentException("Authority must be non-empty"); 358632515b9d0960749ddb1636677d7f12f196d73f7Matthew Williams } 359fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mSyncTarget = SYNC_TARGET_ADAPTER; 360fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAccount = account; 361fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mAuthority = authority; 362fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 363fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 364fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 365fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 366fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Developer-provided extras handed back when sync actually occurs. This bundle is copied 367c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * into the SyncRequest returned by {@link #build()}. 368fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 369fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Example: 370fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <pre> 371fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * String[] syncItems = {"dog", "cat", "frog", "child"}; 372fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * SyncRequest.Builder builder = 373fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * new SyncRequest.Builder() 374fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * .setSyncAdapter(dummyAccount, dummyProvider) 375c43a6bbe88d4e82cccf9fa74ddebc4954889b256Russ Schnapp * .syncOnce(); 376fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 377fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * for (String syncData : syncItems) { 378fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Bundle extras = new Bundle(); 379fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * extras.setString("data", syncData); 380fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder.setExtras(extras); 381fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * ContentResolver.sync(builder.build()); // Each sync() request creates a unique sync. 382fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * } 383fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </pre> 384fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Only values of the following types may be used in the extras bundle: 385fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <ul> 386fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Integer</li> 387fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Long</li> 388fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Boolean</li> 389fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Float</li> 390fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Double</li> 391fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>String</li> 392fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>Account</li> 393fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * <li>null</li> 394fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * </ul> 395fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * If any data is present in the bundle not of this type, build() will 396fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * throw a runtime exception. 397fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 398c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param bundle extras bundle to set. 399fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 400fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExtras(Bundle bundle) { 401fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = bundle; 402fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 403fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 404fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 405fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 406c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY}. 407c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 408c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * A one-off sync operation that fails will be retried with exponential back-off unless 409c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * this is set to false. Not valid for periodic sync and will throw an 410c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> in build(). 411fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 412c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param noRetry true to not retry a failed sync. Default false. 413fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 414c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams public Builder setNoRetry(boolean noRetry) { 415c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams mNoRetry = noRetry; 416fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 417fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 418fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 419fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 420c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS}. 421c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 422c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 423c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 42456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * <p>Throws <code>IllegalArgumentException</code> if called and 42556dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * {@link #setDisallowMetered(boolean)} has been set. 42656dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams * 427c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 428c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param ignoreSettings true to ignore the sync automatically settings. Default false. 429fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 430fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreSettings(boolean ignoreSettings) { 43156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mDisallowMetered && ignoreSettings) { 43256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("setIgnoreSettings(true) after having specified" 43356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams + " sync settings with this builder."); 43456dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 435fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreSettings = ignoreSettings; 436fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 437fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 438fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 439fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 4408cf4e13e466bf7a9dc9a3bee73c8a74f3fc4bb85Ying Wang * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF}. 441fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 442c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Ignoring back-off will force the sync scheduling process to ignore any back-off that was 443c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * the result of a failed sync, as well as to invalidate any {@link SyncResult#delayUntil} 444c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * value that may have been set by the adapter. Successive failures will not honor this 445c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * flag. Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> 446c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * in {@link #build()}. 447c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 448c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param ignoreBackoff ignore back off settings. Default false. 449fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 450fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setIgnoreBackoff(boolean ignoreBackoff) { 451fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIgnoreBackoff = ignoreBackoff; 452fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 453fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 454fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 455fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 456c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Convenience function for setting {@link ContentResolver#SYNC_EXTRAS_MANUAL}. 457c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 458c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 459c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 460c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 461c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param isManual User-initiated sync or not. Default false. 462fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 463fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setManual(boolean isManual) { 464fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mIsManual = isManual; 465fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 466fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 467fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 468fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 469c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * An expedited sync runs immediately and can preempt other non-expedited running syncs. 470c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 471c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * Not valid for periodic sync and will throw an <code>IllegalArgumentException</code> in 472c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * {@link #build()}. 473c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * 474c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * @param expedited whether to run expedited. Default false. 475fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 476fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public Builder setExpedited(boolean expedited) { 477fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mExpedited = expedited; 478fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return this; 479fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 480fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams 481fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams /** 482fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * Performs validation over the request and throws the runtime exception 483c81891c1257895220c00e9ee99968ce305cfdd3bMatthew Williams * <code>IllegalArgumentException</code> if this validation fails. 484fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * 485fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * @return a SyncRequest with the information contained within this 486fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams * builder. 487fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams */ 488fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams public SyncRequest build() { 489fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams // Validate the extras bundle 49068e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams ContentResolver.validateSyncExtrasBundle(mCustomExtras); 491fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mCustomExtras == null) { 492fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams mCustomExtras = new Bundle(); 493fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 49468e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // Combine builder extra flags into the config bundle. 49568e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras = new Bundle(); 496fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreBackoff) { 49768e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, true); 498fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 49956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams if (mDisallowMetered) { 50056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_DISALLOW_METERED, true); 501fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 502fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIgnoreSettings) { 50368e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, true); 504fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 505fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mNoRetry) { 50668e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_DO_NOT_RETRY, true); 507fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 508fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mExpedited) { 50968e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_EXPEDITED, true); 510fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 511fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mIsManual) { 51256dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_BACKOFF, true); 51356dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams mSyncConfigExtras.putBoolean(ContentResolver.SYNC_EXTRAS_IGNORE_SETTINGS, true); 514fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 515fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncType == SYNC_TYPE_PERIODIC) { 51668e39c3411d97ba2fe3ef5e33260b31fc73c934fMatthew Williams // If this is a periodic sync ensure than invalid extras were not set. 51764939ae385edf615ac2912060df5624dbaf57cabMatthew Williams if (ContentResolver.invalidPeriodicExtras(mCustomExtras) || 51856dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams ContentResolver.invalidPeriodicExtras(mSyncConfigExtras)) { 51956dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams throw new IllegalArgumentException("Illegal extras were set"); 52056dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 52156dbf8f23677d28615e61ef2fbb0e738cca02528Matthew Williams } 522fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams // Ensure that a target for the sync has been set. 523fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams if (mSyncTarget == SYNC_TARGET_UNKNOWN) { 52464939ae385edf615ac2912060df5624dbaf57cabMatthew Williams throw new IllegalArgumentException("Must specify an adapter with" + 52564939ae385edf615ac2912060df5624dbaf57cabMatthew Williams " setSyncAdapter(Account, String"); 526fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 527fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams return new SyncRequest(this); 528fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams } 52964939ae385edf615ac2912060df5624dbaf57cabMatthew Williams } 530fa77418134c6f1f80af225a78819f069e9c974fbMatthew Williams} 531