public static class SyncRequest.Builder extends Object
Constructor and Description |
---|
Builder() |
Modifier and Type | Method and Description |
---|---|
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 ignoreSettings) 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 |
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.
|
public SyncRequest.Builder syncOnce()
SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce();
public SyncRequest.Builder syncPeriodic(long pollFrequency, long beforeSeconds)
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
set to true. If any are supplied then an IllegalArgumentException
will
be thrown.pollFrequency
- the amount of time in seconds that you wish
to elapse between periodic syncs. A minimum period of 1 hour is enforced.beforeSeconds
- 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)public SyncRequest.Builder setDisallowMetered(boolean disallow)
IllegalArgumentException
if called and
setIgnoreSettings(boolean ignoreSettings)
has already been called.disallow
- true to allow this transfer on metered networks. Default false.public SyncRequest.Builder setRequiresCharging(boolean requiresCharging)
requiresCharging
- true if sync requires the phone to be plugged in. Default false.public SyncRequest.Builder setSyncAdapter(Account account, String authority)
authority
- A String identifying the content provider to be synced.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, thepublic SyncRequest.Builder setExtras(Bundle bundle)
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:
bundle
- extras bundle to set.public SyncRequest.Builder setNoRetry(boolean noRetry)
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().noRetry
- true to not retry a failed sync. Default false.public SyncRequest.Builder setIgnoreSettings(boolean ignoreSettings)
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.
ignoreSettings
- true to ignore the sync automatically settings. Default false.public SyncRequest.Builder setIgnoreBackoff(boolean ignoreBackoff)
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()
.ignoreBackoff
- ignore back off settings. Default false.public SyncRequest.Builder setManual(boolean isManual)
ContentResolver.SYNC_EXTRAS_MANUAL
.
Not valid for periodic sync and will throw an IllegalArgumentException
in
build()
.isManual
- User-initiated sync or not. Default false.public SyncRequest.Builder setExpedited(boolean expedited)
IllegalArgumentException
in
build()
.expedited
- whether to run expedited. Default false.public SyncRequest build()
IllegalArgumentException
if this validation fails.