Builder
open class Builder
kotlin.Any | |
↳ | 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 | |
---|---|
open SyncRequest! |
build() Performs validation over the request and throws the runtime exception |
open SyncRequest.Builder! |
setDisallowMetered(disallow: Boolean) Will throw an |
open SyncRequest.Builder! |
setExpedited(expedited: Boolean) An expedited sync runs immediately and can preempt other non-expedited running syncs. |
open SyncRequest.Builder! |
Developer-provided extras handed back when sync actually occurs. |
open SyncRequest.Builder! |
setIgnoreBackoff(ignoreBackoff: Boolean) Convenience function for setting |
open SyncRequest.Builder! |
setIgnoreSettings(ignoreSettings: Boolean) Convenience function for setting |
open SyncRequest.Builder! |
Convenience function for setting |
open SyncRequest.Builder! |
setNoRetry(noRetry: Boolean) Convenience function for setting |
open SyncRequest.Builder! |
setRequiresCharging(requiresCharging: Boolean) Specify whether the sync requires the phone to be plugged in. |
open SyncRequest.Builder |
setScheduleAsExpeditedJob(scheduleAsExpeditedJob: Boolean) Convenience function for setting |
open SyncRequest.Builder! |
setSyncAdapter(account: Account!, authority: String!) Specify an authority and account for this transfer. |
open SyncRequest.Builder! |
syncOnce() Request that a sync occur immediately. |
open SyncRequest.Builder! |
syncPeriodic(pollFrequency: Long, beforeSeconds: Long) Build a periodic sync. |
Public constructors
Public methods
build
open fun build(): SyncRequest!
Performs validation over the request and throws the runtime exception IllegalArgumentException
if this validation fails.
Return | |
---|---|
SyncRequest! |
a SyncRequest with the information contained within this builder. |
setDisallowMetered
open fun setDisallowMetered(disallow: Boolean): SyncRequest.Builder!
Will throw an IllegalArgumentException
if called and setIgnoreSettings(boolean ignoreSettings)
has already been called.
Parameters | |
---|---|
disallow |
Boolean: true to allow this transfer on metered networks. Default false. |
setExpedited
open fun setExpedited(expedited: Boolean): SyncRequest.Builder!
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. |
setExtras
open fun setExtras(bundle: Bundle!): SyncRequest.Builder!
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
Parameters | |
---|---|
bundle |
Bundle!: extras bundle to set. |
setIgnoreBackoff
open fun setIgnoreBackoff(ignoreBackoff: Boolean): SyncRequest.Builder!
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. |
setIgnoreSettings
open fun setIgnoreSettings(ignoreSettings: Boolean): SyncRequest.Builder!
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. |
setManual
open fun setManual(isManual: Boolean): SyncRequest.Builder!
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. |
setNoRetry
open fun setNoRetry(noRetry: Boolean): SyncRequest.Builder!
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. |
setRequiresCharging
open fun setRequiresCharging(requiresCharging: Boolean): SyncRequest.Builder!
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. |
setScheduleAsExpeditedJob
open fun setScheduleAsExpeditedJob(scheduleAsExpeditedJob: Boolean): SyncRequest.Builder
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. |
Return | |
---|---|
SyncRequest.Builder |
This value cannot be null . |
setSyncAdapter
open fun setSyncAdapter(
account: Account!,
authority: String!
): SyncRequest.Builder!
Specify an authority and account for this transfer.
Parameters | |
---|---|
authority |
String!: A String identifying the content provider to be synced. |
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 |
syncOnce
open fun syncOnce(): SyncRequest.Builder!
Request that a sync occur immediately. Example
SyncRequest.Builder builder = (new SyncRequest.Builder()).syncOnce();
syncPeriodic
open fun syncPeriodic(
pollFrequency: Long,
beforeSeconds: Long
): SyncRequest.Builder!
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 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) |