Added in API level 19

Summary: Ctors | Methods | Inherited Methods

SyncRequest.Builder

---

Kotlin |Java

public static class SyncRequest.Builder
extends Object

java.lang.Object
↳	android.content.SyncRequest.Builder

---

Builder class for a SyncRequest. As you build your SyncRequest this class will also perform validation.

Summary

Public constructors
Builder()

Public methods
SyncRequest	build() Performs validation over the request and throws the runtime exception IllegalArgumentException if this validation fails.
SyncRequest.Builder	setDisallowMetered(boolean disallow) Will throw an IllegalArgumentException if called and setIgnoreSettings(boolean) has already been called.
SyncRequest.Builder	setExpedited(boolean expedited) An expedited sync runs immediately and can preempt other non-expedited running syncs.
SyncRequest.Builder	setExtras(Bundle bundle) Developer-provided extras handed back when sync actually occurs.
SyncRequest.Builder	setIgnoreBackoff(boolean ignoreBackoff) Convenience function for setting ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF.
SyncRequest.Builder	setIgnoreSettings(boolean ignoreSettings) Convenience function for setting ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS.
SyncRequest.Builder	setManual(boolean isManual) Convenience function for setting ContentResolver#SYNC_EXTRAS_MANUAL.
SyncRequest.Builder	setNoRetry(boolean noRetry) Convenience function for setting ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY.
SyncRequest.Builder	setRequiresCharging(boolean requiresCharging) Specify whether the sync requires the phone to be plugged in.
SyncRequest.Builder	setScheduleAsExpeditedJob(boolean scheduleAsExpeditedJob) Convenience function for setting ContentResolver#SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB.
SyncRequest.Builder	setSyncAdapter(Account account, String authority) Specify an authority and account for this transfer.
SyncRequest.Builder	syncOnce() Request that a sync occur immediately.
SyncRequest.Builder	syncPeriodic(long pollFrequency, long beforeSeconds) Build a periodic sync.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Builder

Added in API level 19

public Builder ()

Public methods

build

Added in API level 19

public SyncRequest build ()

Performs validation over the request and throws the runtime exception IllegalArgumentException if this validation fails.

Returns
SyncRequest	a SyncRequest with the information contained within this builder.

setDisallowMetered

Added in API level 19

public SyncRequest.Builder setDisallowMetered (boolean disallow)

Will throw an IllegalArgumentException if called and setIgnoreSettings(boolean) has already been called.

Parameters
disallow	boolean: true to allow this transfer on metered networks. Default false.

Returns
SyncRequest.Builder

setExpedited

Added in API level 19

public SyncRequest.Builder setExpedited (boolean expedited)

An expedited sync runs immediately and can preempt other non-expedited running syncs. Not valid for periodic sync and will throw an IllegalArgumentException in build().

Parameters
expedited	boolean: whether to run expedited. Default false.

Returns
SyncRequest.Builder

setExtras

Added in API level 19

public SyncRequest.Builder setExtras (Bundle bundle)

Developer-provided extras handed back when sync actually occurs. This bundle is copied into the SyncRequest returned by build(). Example:

   String[] syncItems = {"dog", "cat", "frog", "child"};
   SyncRequest.Builder builder =
     new SyncRequest.Builder()
       .setSyncAdapter(dummyAccount, dummyProvider)
       .syncOnce();

   for (String syncData : syncItems) {
     Bundle extras = new Bundle();
     extras.setString("data", syncData);
     builder.setExtras(extras);
     ContentResolver.sync(builder.build()); // Each sync() request creates a unique sync.
   }
 

Only values of the following types may be used in the extras bundle:

• Integer
• Long
• Boolean
• Float
• Double
• String
• Account
• null

If any data is present in the bundle not of this type, build() will throw a runtime exception.

Parameters
bundle	Bundle: extras bundle to set.

Returns
SyncRequest.Builder

setIgnoreBackoff

Added in API level 19

public SyncRequest.Builder setIgnoreBackoff (boolean ignoreBackoff)

Convenience function for setting ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF. Ignoring back-off will force the sync scheduling process to ignore any back-off that was the result of a failed sync, as well as to invalidate any SyncResult#delayUntil value that may have been set by the adapter. Successive failures will not honor this flag. Not valid for periodic sync and will throw an IllegalArgumentException in build().

Parameters
ignoreBackoff	boolean: ignore back off settings. Default false.

Returns
SyncRequest.Builder

setIgnoreSettings

Added in API level 19

public SyncRequest.Builder setIgnoreSettings (boolean ignoreSettings)

Convenience function for setting ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS. Not valid for periodic sync and will throw an IllegalArgumentException in build().

Throws IllegalArgumentException if called and setDisallowMetered(boolean) has been set.

Parameters
ignoreSettings	boolean: true to ignore the sync automatically settings. Default false.

Returns
SyncRequest.Builder

setManual

Added in API level 19

public SyncRequest.Builder setManual (boolean isManual)

Convenience function for setting ContentResolver#SYNC_EXTRAS_MANUAL. Not valid for periodic sync and will throw an IllegalArgumentException in build().

Parameters
isManual	boolean: User-initiated sync or not. Default false.

Returns
SyncRequest.Builder

setNoRetry

Added in API level 19

public SyncRequest.Builder setNoRetry (boolean noRetry)

Convenience function for setting ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY. A one-off sync operation that fails will be retried with exponential back-off unless this is set to false. Not valid for periodic sync and will throw an IllegalArgumentException in build().

Parameters
noRetry	boolean: true to not retry a failed sync. Default false.

Returns
SyncRequest.Builder

setRequiresCharging

Added in API level 24

public SyncRequest.Builder setRequiresCharging (boolean requiresCharging)

Specify whether the sync requires the phone to be plugged in.

Parameters
requiresCharging	boolean: true if sync requires the phone to be plugged in. Default false.

Returns
SyncRequest.Builder

setScheduleAsExpeditedJob

Added in API level 31

public SyncRequest.Builder setScheduleAsExpeditedJob (boolean scheduleAsExpeditedJob)

Convenience function for setting ContentResolver#SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB.

Not to be confused with ContentResolver#SYNC_EXTRAS_EXPEDITED.

Not valid for periodic syncs, expedited syncs, and syncs that require charging - an IllegalArgumentException will be thrown in build().

Parameters
scheduleAsExpeditedJob	boolean: whether to schedule as an expedited job. Default false.

Returns
SyncRequest.Builder	This value cannot be null.

setSyncAdapter

Added in API level 19

public SyncRequest.Builder setSyncAdapter (Account account, 
                String authority)

Specify an authority and account for this transfer.

Parameters
account	Account: Account to sync. Can be null unless this is a periodic sync, for which verification by the ContentResolver will fail. If a sync is performed without an account, the
authority	String: A String identifying the content provider to be synced.

Returns
SyncRequest.Builder

syncOnce

Added in API level 19

public SyncRequest.Builder syncOnce ()

Request that a sync occur immediately. Example

     SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce();
 

Returns
SyncRequest.Builder

syncPeriodic

Added in API level 19

public SyncRequest.Builder syncPeriodic (long pollFrequency, 
                long beforeSeconds)

Build a periodic sync. Either this or syncOnce() must be called for this builder. Syncs are identified by target android.provider and by the contents of the extras bundle. You cannot reuse the same builder for one-time syncs after having specified a periodic sync (by calling this function). If you do, an IllegalArgumentException will be thrown.

The bundle for a periodic sync can be queried by applications with the correct permissions using ContentResolver#getPeriodicSyncs(Account account, String provider), so no sensitive data should be transferred here. Example usage.

     Request a periodic sync every 5 hours with 20 minutes of flex.
     SyncRequest.Builder builder =
         (new SyncRequest.Builder()).syncPeriodic(5 * HOUR_IN_SECS, 20 * MIN_IN_SECS);

     Schedule a periodic sync every hour at any point in time during that hour.
     SyncRequest.Builder builder =
         (new SyncRequest.Builder()).syncPeriodic(1 * HOUR_IN_SECS, 1 * HOUR_IN_SECS);
 

N.B.: Periodic syncs are not allowed to have any of ContentResolver#SYNC_EXTRAS_DO_NOT_RETRY, ContentResolver#SYNC_EXTRAS_IGNORE_BACKOFF, ContentResolver#SYNC_EXTRAS_IGNORE_SETTINGS, ContentResolver#SYNC_EXTRAS_INITIALIZE, ContentResolver#SYNC_EXTRAS_FORCE, ContentResolver#SYNC_EXTRAS_EXPEDITED, ContentResolver#SYNC_EXTRAS_MANUAL, ContentResolver#SYNC_EXTRAS_SCHEDULE_AS_EXPEDITED_JOB set to true. If any are supplied then an IllegalArgumentException will be thrown.

Parameters
pollFrequency	long: the amount of time in seconds that you wish to elapse between periodic syncs. A minimum period of 1 hour is enforced.
beforeSeconds	long: the amount of flex time in seconds before pollFrequency that you permit for the sync to take place. Must be less than pollFrequency and greater than MAX(5% of pollFrequency, 5 minutes)

Returns
SyncRequest.Builder