Android APIs
public static class

SyncRequest.Builder

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

Class Overview

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

Summary

Public Constructors
SyncRequest.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)
SyncRequest.Builder setExpedited(boolean expedited)
An expedited sync runs immediately and will preempt another non-expedited running sync.
SyncRequest.Builder setExtras(Bundle bundle)
Optional developer-provided extras handed back in onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) occurs.
SyncRequest.Builder setIgnoreBackoff(boolean ignoreBackoff)
Convenience function for setting SYNC_EXTRAS_IGNORE_BACKOFF.
SyncRequest.Builder setIgnoreSettings(boolean ignoreSettings)
Convenience function for setting SYNC_EXTRAS_IGNORE_SETTINGS.
SyncRequest.Builder setManual(boolean isManual)
Convenience function for setting SYNC_EXTRAS_MANUAL.
SyncRequest.Builder setNoRetry(boolean noRetry)
Convenience function for setting SYNC_EXTRAS_DO_NOT_RETRY.
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.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public SyncRequest.Builder ()

Added in API level 19

Public Methods

public SyncRequest build ()

Added in API level 19

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

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

public SyncRequest.Builder setDisallowMetered (boolean disallow)

Added in API level 19

Parameters
disallow true to enforce that this transfer not occur on metered networks. Default false.

public SyncRequest.Builder setExpedited (boolean expedited)

Added in API level 19

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

Parameters
expedited whether to run expedited. Default false.

public SyncRequest.Builder setExtras (Bundle bundle)

Added in API level 19

Optional developer-provided extras handed back in onPerformSync(Account, Bundle, String, ContentProviderClient, SyncResult) 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(5 * MINUTES_IN_SECS);

   for (String syncData : syncItems) {
     Bundle extras = new Bundle();
     extras.setString("data", syncData);
     builder.setExtras(extras);
     ContentResolver.sync(builder.build()); // Each sync() request is for 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 extras bundle to set.

public SyncRequest.Builder setIgnoreBackoff (boolean ignoreBackoff)

Added in API level 19

Convenience function for setting SYNC_EXTRAS_IGNORE_BACKOFF. Force the sync scheduling process to ignore any back-off that was the result of a failed sync, as well as to invalidate any 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 ignore back-off settings. Default false.

public SyncRequest.Builder setIgnoreSettings (boolean ignoreSettings)

Added in API level 19

Convenience function for setting SYNC_EXTRAS_IGNORE_SETTINGS. A sync can specify that system sync settings be ignored (user has turned sync off). Not valid for periodic sync and will throw an IllegalArgumentException in build().

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

public SyncRequest.Builder setManual (boolean isManual)

Added in API level 19

Convenience function for setting SYNC_EXTRAS_MANUAL. A manual sync is functionally equivalent to calling setIgnoreBackoff(boolean) and setIgnoreSettings(boolean). Not valid for periodic sync and will throw an IllegalArgumentException in build().

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

public SyncRequest.Builder setNoRetry (boolean noRetry)

Added in API level 19

Convenience function for setting 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 true to not retry a failed sync. Default false.

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

Added in API level 19

Specify an authority and account for this transfer.

Parameters
account Account to sync. Can be null unless this is a periodic sync.
authority String identifying which content provider to sync.

public SyncRequest.Builder syncOnce ()

Added in API level 19

Request that a sync occur immediately. Example

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

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

Added in API level 19

Build a periodic sync. Either this or syncOnce() must be called for this builder. Syncs are identified by target android.provider/Account and by the contents of the extras bundle. You cannot reuse the same builder for one-time syncs (by calling this function) after having specified a periodic sync. If you do, an IllegalArgumentException will be thrown. 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 SYNC_EXTRAS_DO_NOT_RETRY, SYNC_EXTRAS_IGNORE_BACKOFF, SYNC_EXTRAS_IGNORE_SETTINGS, SYNC_EXTRAS_INITIALIZE, SYNC_EXTRAS_FORCE, SYNC_EXTRAS_EXPEDITED, SYNC_EXTRAS_MANUAL set to true. If any are supplied then an IllegalArgumentException will be thrown.

Parameters
pollFrequency the amount of time in seconds that you wish to elapse between periodic syncs.
beforeSeconds the amount of flex time in seconds before pollFrequency that you permit for the sync to take place. Must be less than pollFrequency.