BasicSyncAdapter.zip
The sync adapter component in your app encapsulates the code for the tasks that transfer data between the device and a server. Based on the scheduling and triggers you provide in your app, the sync adapter framework runs the code in the sync adapter component. To add a sync adapter component to your app, you need to add the following pieces:
This lesson shows you how to define these elements.
In this part of the lesson you learn how to create the sync adapter class that encapsulates the data transfer code. Creating the class includes extending the sync adapter base class, defining constructors for the class, and implementing the method where you define the data transfer tasks.
To create the sync adapter component, start by extending {@link android.content.AbstractThreadedSyncAdapter} and writing its constructors. Use the constructors to run setup tasks each time your sync adapter component is created from scratch, just as you use {@link android.app.Activity#onCreate Activity.onCreate()} to set up an activity. For example, if your app uses a content provider to store data, use the constructors to get a {@link android.content.ContentResolver} instance. Since a second form of the constructor was added in Android platform version 3.0 to support the {@code parallelSyncs} argument, you need to create two forms of the constructor to maintain compatibility.
Note: The sync adapter framework is designed to work with sync adapter components that are singleton instances. Instantiating the sync adapter component is covered in more detail in the section Bind the Sync Adapter to the Framework.
The following example shows you how to implement {@link android.content.AbstractThreadedSyncAdapter}and its constructors:
/**
* Handle the transfer of data between a server and an
* app, using the Android sync adapter framework.
*/
public class SyncAdapter extends AbstractThreadedSyncAdapter {
...
// Global variables
// Define a variable to contain a content resolver instance
ContentResolver mContentResolver;
/**
* Set up the sync adapter
*/
public SyncAdapter(Context context, boolean autoInitialize) {
super(context, autoInitialize);
/*
* If your app uses a content resolver, get an instance of it
* from the incoming Context
*/
mContentResolver = context.getContentResolver();
}
...
/**
* Set up the sync adapter. This form of the
* constructor maintains compatibility with Android 3.0
* and later platform versions
*/
public SyncAdapter(
Context context,
boolean autoInitialize,
boolean allowParallelSyncs) {
super(context, autoInitialize, allowParallelSyncs);
/*
* If your app uses a content resolver, get an instance of it
* from the incoming Context
*/
mContentResolver = context.getContentResolver();
...
}
The sync adapter component does not automatically do data transfer. Instead, it encapsulates your data transfer code, so that the sync adapter framework can run the data transfer in the background, without involvement from your app. When the framework is ready to sync your application's data, it invokes your implementation of the method {@link android.content.AbstractThreadedSyncAdapter#onPerformSync onPerformSync()}.
To facilitate the transfer of data from your main app code to the sync adapter component, the sync adapter framework calls {@link android.content.AbstractThreadedSyncAdapter#onPerformSync onPerformSync()} with the following arguments:
The following snippet shows the overall structure of {@link android.content.AbstractThreadedSyncAdapter#onPerformSync onPerformSync()}:
/*
* Specify the code you want to run in the sync adapter. The entire
* sync adapter runs in a background thread, so you don't have to set
* up your own background processing.
*/
@Override
public void onPerformSync(
Account account,
Bundle extras,
String authority,
ContentProviderClient provider,
SyncResult syncResult) {
/*
* Put the data transfer code here.
*/
...
}
While the actual implementation of {@link android.content.AbstractThreadedSyncAdapter#onPerformSync onPerformSync()} is specific to your app's data synchronization requirements and server connection protocols, there are a few general tasks your implementation should perform:
Note: The sync adapter framework runs {@link android.content.AbstractThreadedSyncAdapter#onPerformSync onPerformSync()} on a background thread, so you don't have to set up your own background processing.
In addition to your sync-related tasks, you should try to combine your regular network-related tasks and add them to {@link android.content.AbstractThreadedSyncAdapter#onPerformSync onPerformSync()}. By concentrating all of your network tasks in this method, you conserve the battery power that's needed to start and stop the network interfaces. To learn more about making network access more efficient, see the training class Transferring Data Without Draining the Battery, which describes several network access tasks you can include in your data transfer code.
You now have your data transfer code encapsulated in a sync adapter component, but you have to provide the framework with access to your code. To do this, you need to create a bound {@link android.app.Service} that passes a special Android binder object from the sync adapter component to the framework. With this binder object, the framework can invoke the {@link android.content.AbstractThreadedSyncAdapter#onPerformSync onPerformSync()} method and pass data to it.
Instantiate your sync adapter component as a singleton in the {@link android.app.Service#onCreate onCreate()} method of the service. By instantiating the component in {@link android.app.Service#onCreate onCreate()}, you defer creating it until the service starts, which happens when the framework first tries to run your data transfer. You need to instantiate the component in a thread-safe manner, in case the sync adapter framework queues up multiple executions of your sync adapter in response to triggers or scheduling.
For example, the following snippet shows you how to create a class that implements the bound {@link android.app.Service}, instantiates your sync adapter component, and gets the Android binder object:
package com.example.android.syncadapter;
/**
* Define a Service that returns an {@link android.os.IBinder} for the
* sync adapter class, allowing the sync adapter framework to call
* onPerformSync().
*/
public class SyncService extends Service {
// Storage for an instance of the sync adapter
private static SyncAdapter sSyncAdapter = null;
// Object to use as a thread-safe lock
private static final Object sSyncAdapterLock = new Object();
/*
* Instantiate the sync adapter object.
*/
@Override
public void onCreate() {
/*
* Create the sync adapter as a singleton.
* Set the sync adapter as syncable
* Disallow parallel syncs
*/
synchronized (sSyncAdapterLock) {
if (sSyncAdapter == null) {
sSyncAdapter = new SyncAdapter(getApplicationContext(), true);
}
}
}
/**
* Return an object that allows the system to invoke
* the sync adapter.
*
*/
@Override
public IBinder onBind(Intent intent) {
/*
* Get the object that allows external processes
* to call onPerformSync(). The object is created
* in the base class code when the SyncAdapter
* constructors call super()
*/
return sSyncAdapter.getSyncAdapterBinder();
}
}
Note: To see a more detailed example of a bound service for a sync adapter, see the sample app.
The sync adapter framework requires each sync adapter to have an account type. You declared the account type value in the section Add the Authenticator Metadata File. Now you have to set up this account type in the Android system. To set up the account type, add a dummy account that uses the account type by calling {@link android.accounts.AccountManager#addAccountExplicitly addAccountExplicitly()}.
The best place to call the method is in the {@link android.support.v4.app.FragmentActivity#onCreate onCreate()} method of your app's opening activity. The following code snippet shows you how to do this:
public class MainActivity extends FragmentActivity {
...
...
// Constants
// The authority for the sync adapter's content provider
public static final String AUTHORITY = "com.example.android.datasync.provider";
// An account type, in the form of a domain name
public static final String ACCOUNT_TYPE = "example.com";
// The account name
public static final String ACCOUNT = "dummyaccount";
// Instance fields
Account mAccount;
...
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
...
// Create the dummy account
mAccount = CreateSyncAccount(this);
...
}
...
/**
* Create a new dummy account for the sync adapter
*
* @param context The application context
*/
public static Account CreateSyncAccount(Context context) {
// Create the account type and default account
Account newAccount = new Account(
ACCOUNT, ACCOUNT_TYPE);
// Get an instance of the Android account manager
AccountManager accountManager =
(AccountManager) context.getSystemService(
ACCOUNT_SERVICE);
/*
* Add the account and account type, no password or user data
* If successful, return the Account object, otherwise report an error.
*/
if (accountManager.addAccountExplicitly(newAccount, null, null)) {
/*
* If you don't set android:syncable="true" in
* in your <provider> element in the manifest,
* then call context.setIsSyncable(account, AUTHORITY, 1)
* here.
*/
} else {
/*
* The account exists or some other error occurred. Log this, report it,
* or handle it internally.
*/
}
}
...
}
To plug your sync adapter component into the framework, you need to provide the framework with metadata that describes the component and provides additional flags. The metadata specifies the account type you've created for your sync adapter, declares a content provider authority associated with your app, controls a part of the system user interface related to sync adapters, and declares other sync-related flags. Declare this metadata in a special XML file stored in the {@code /res/xml/} directory in your app project. You can give any name to the file, although it's usually called {@code syncadapter.xml}.
This XML file contains a single XML element <sync-adapter> that has the
following attributes:
android:contentAuthorityandroid:authorities
in the <provider> element you added to your app manifest. This attribute is
described in more detail in the section
Declare the Provider in the Manifest.
android:authorities
attribute of the <provider> element that declares your provider in your app manifest.
android:accountTypeThe following example shows the XML for a sync adapter that uses a single dummy account and only does downloads.
<?xml version="1.0" encoding="utf-8"?>
<sync-adapter
xmlns:android="http://schemas.android.com/apk/res/android"
android:contentAuthority="com.example.android.datasync.provider"
android:accountType="com.android.example.datasync"
android:userVisible="false"
android:supportsUploading="false"
android:allowParallelSyncs="false"
android:isAlwaysSyncable="true"/>
Once you've added the sync adapter component to your app, you have to request permissions related to using the component, and you have to declare the bound {@link android.app.Service} you've added.
Since the sync adapter component runs code that transfers data between the network and the device, you need to request permission to access the Internet. In addition, your app needs to request permission to read and write sync adapter settings, so you can control the sync adapter programmatically from other components in your app. You also need to request a special permission that allows your app to use the authenticator component you created in the lesson Creating a Stub Authenticator.
To request these permissions, add the following to your app manifest as child elements of
<manifest>:
The following snippet shows how to add the permissions:
<manifest>
...
<uses-permission
android:name="android.permission.INTERNET"/>
<uses-permission
android:name="android.permission.READ_SYNC_SETTINGS"/>
<uses-permission
android:name="android.permission.WRITE_SYNC_SETTINGS"/>
<uses-permission
android:name="android.permission.AUTHENTICATE_ACCOUNTS"/>
...
</manifest>
Finally, to declare the bound {@link android.app.Service} that the framework uses to
interact with your sync adapter, add the following XML to your app manifest as a child element
of <application>:
<service
android:name="com.example.android.datasync.SyncService"
android:exported="true"
android:process=":sync">
<intent-filter>
<action android:name="android.content.SyncAdapter"/>
</intent-filter>
<meta-data android:name="android.content.SyncAdapter"
android:resource="@xml/syncadapter" />
</service>
The
<intent-filter>
element sets up a filter that's triggered by the intent action
{@code android.content.SyncAdapter}, sent by the system to run the sync adapter. When the filter
is triggered, the system starts the bound service you've created, which in this example is
{@code SyncService}. The attribute
android:exported="true"
allows processes other than your app (including the system) to access the
{@link android.app.Service}. The attribute
android:process=":sync"
tells the system to run the {@link android.app.Service} in a global shared process named
{@code sync}. If you have multiple sync adapters in your app they can share this process,
which reduces overhead.
The
<meta-data>
element provides provides the name of the sync adapter metadata XML file you created previously.
The
android:name
attribute indicates that this metadata is for the sync adapter framework. The
android:resource
element specifies the name of the metadata file.
You now have all of the components for your sync adapter. The next lesson shows you how to tell the sync adapter framework to run your sync adapter, either in response to an event or on a regular schedule.