創(chuàng)建 Sync Adpater

編寫:jdneo - 原文:http://developer.android.com/training/sync-adapters/creating-sync-adapter.html

設(shè)備和服務(wù)器之間執(zhí)行數(shù)據(jù)傳輸?shù)拇a會(huì)封裝在應(yīng)用的 Sync Adapter 組件中。Sync Adapter 框架會(huì)基于我們的調(diào)度和觸發(fā)操作，運(yùn)行 Sync Adapter 組件中的代碼。要將同步適配組件添加到應(yīng)用當(dāng)中，我們需要添加下列部件：

Sync Adapter 類

將我們的數(shù)據(jù)傳輸代碼封裝到一個(gè)與 Sync Adapter 框架兼容的接口當(dāng)中。

綁定 Service

通過一個(gè)綁定服務(wù)，允許 Sync Adapter 框架運(yùn)行 Sync Adapter 類中的代碼。

Sync Adapter 的 XML 元數(shù)據(jù)文件

該文件包含了有關(guān) Sync Adapter 的信息?？蚣軙?huì)根據(jù)該文件確定應(yīng)該如何加載并調(diào)度數(shù)據(jù)傳輸任務(wù)。

應(yīng)用 manifest 清單文件的聲明

需要在應(yīng)用的 manifest 清單文件中聲明綁定服務(wù)；同時(shí)還需要指出 Sync Adapter 的元數(shù)據(jù)。

這節(jié)課將會(huì)向我們展示如何定義他們。

創(chuàng)建一個(gè) Sync Adapter 類

在這部分課程中，我們將會(huì)學(xué)習(xí)如何創(chuàng)建封裝了數(shù)據(jù)傳輸代碼的 Sync Adapter 類。創(chuàng)建該類需要繼承 Sync Adapter 的基類；為該類定義構(gòu)造函數(shù)；以及實(shí)現(xiàn)相關(guān)的方法。在這些方法中，我們定義數(shù)據(jù)傳輸任務(wù)。

繼承 Sync Adapter 基類：AbstractThreadedSyncAdapter

要?jiǎng)?chuàng)建 Sync Adapter 組件，首先繼承 AbstractThreadedSyncAdapter，然后編寫它的構(gòu)造函數(shù)。與使用 Activity.onCreate() 配置 Activity 時(shí)一樣，每次我們重新創(chuàng)建 Sync Adapter 組件的時(shí)候，使用構(gòu)造函數(shù)執(zhí)行相關(guān)的配置。例如，如果我們的應(yīng)用使用一個(gè) Content Provider 來存儲(chǔ)數(shù)據(jù)，那么使用構(gòu)造函數(shù)來獲取一個(gè) ContentResolver 實(shí)例。由于從 Android 3.0 開始添加了第二種形式的構(gòu)造函數(shù)，來支持 parallelSyncs 參數(shù)，所以我們需要?jiǎng)?chuàng)建兩種形式的構(gòu)造函數(shù)來保證兼容性。

Note：Sync Adapter 框架是設(shè)計(jì)成和 Sync Adapter 組件的單例一起工作的。實(shí)例化 Sync Adapter 組件的更多細(xì)節(jié)，會(huì)在后面的章節(jié)中展開。

下面的代碼展示了如何實(shí)現(xiàn) AbstractThreadedSyncAdapter 和它的構(gòu)造函數(shù)：

/**
 * 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();
        ...
    }

在 onPerformSync() 中添加數(shù)據(jù)傳輸代碼

Sync Adapter 組件并不會(huì)自動(dòng)地執(zhí)行數(shù)據(jù)傳輸。它對(duì)我們的數(shù)據(jù)傳輸代碼進(jìn)行封裝，使得 Sync Adapter 框架可以在后臺(tái)執(zhí)行數(shù)據(jù)傳輸，而不會(huì)牽連到我們的應(yīng)用。當(dāng)框架準(zhǔn)備同步我們的應(yīng)用數(shù)據(jù)時(shí)，它會(huì)調(diào)用我們所實(shí)現(xiàn)的 onPerformSync() 方法。

為了便于將數(shù)據(jù)從應(yīng)用程序轉(zhuǎn)移到 Sync Adapter 組件中，Sync Adapter 框架調(diào)用 onPerformSync()，它具有下面的參數(shù)：

Account

該 Account 對(duì)象與觸發(fā) Sync Adapter 的事件相關(guān)聯(lián)。如果服務(wù)端不需要使用賬戶，那么我們不需要使用這個(gè)對(duì)象內(nèi)的信息。

Extras

一個(gè) Bundle 對(duì)象，它包含了一些標(biāo)識(shí)，這些標(biāo)識(shí)由觸發(fā) Sync Adapter 的事件所發(fā)送。

Authority

系統(tǒng)中某個(gè) Content Provider 的 Authority。我們的應(yīng)用必須要有訪問它的權(quán)限。通常，該 Authority 對(duì)應(yīng)于應(yīng)用的 Content Provider。

Content provider client

ContentProviderClient 針對(duì)于由 Authority 參數(shù)所指向的Content Provider。ContentProviderClient 是一個(gè) Content Provider 的輕量級(jí)共有接口。它的基本功能和 ContentResolver 一樣。如果我們正在使用 Content Provider 來存儲(chǔ)應(yīng)用數(shù)據(jù)，那么我們可以利用它連接 Content Provider。反之，則將其忽略。

Sync result

一個(gè) SyncResult 對(duì)象，我們可以使用它將信息發(fā)送給 Sync Adapter 框架。

下面的代碼片段展示了 onPerformSync() 函數(shù)的整體結(jié)構(gòu)：

    /*
     * 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.
     */
    ...
    }

雖然實(shí)際的onPerformSync() 實(shí)現(xiàn)是要根據(jù)應(yīng)用數(shù)據(jù)的同步需求以及服務(wù)器的連接協(xié)議來制定，但是我們的實(shí)現(xiàn)只需要執(zhí)行一些常規(guī)任務(wù)：

連接到一個(gè)服務(wù)器

盡管我們可以假定在開始傳輸數(shù)據(jù)時(shí)，已經(jīng)獲取到了網(wǎng)絡(luò)連接，但是 Sync Adapter 框架并不會(huì)自動(dòng)地連接到一個(gè)服務(wù)器。

下載和上傳數(shù)據(jù)

Sync Adapter 不會(huì)自動(dòng)執(zhí)行數(shù)據(jù)傳輸。如果我們想要從服務(wù)器下載數(shù)據(jù)并將它存儲(chǔ)到 Content Provider 中，我們必須提供請(qǐng)求數(shù)據(jù)，下載數(shù)據(jù)和將數(shù)據(jù)插入到 Provider 中的代碼。類似地，如果我們想把數(shù)據(jù)發(fā)送到服務(wù)器，我們需要從一個(gè)文件，數(shù)據(jù)庫(kù)或者 Provider 中讀取數(shù)據(jù)，并且發(fā)送必需的上傳請(qǐng)求。同時(shí)我們還需要處理在執(zhí)行數(shù)據(jù)傳輸時(shí)所發(fā)生的網(wǎng)絡(luò)錯(cuò)誤。

處理數(shù)據(jù)沖突或者確定當(dāng)前數(shù)據(jù)的狀態(tài)

Sync Adapter 不會(huì)自動(dòng)地解決服務(wù)器數(shù)據(jù)與設(shè)備數(shù)據(jù)之間的沖突。同時(shí)，它也不會(huì)自動(dòng)檢測(cè)服務(wù)器上的數(shù)據(jù)是否比設(shè)備上的數(shù)據(jù)要新，反之亦然。因此，我們必須自己提供處理這些狀況的算法。

清理

在數(shù)據(jù)傳輸?shù)奈猜?，記得要關(guān)閉網(wǎng)絡(luò)連接，清除臨時(shí)文件和緩存。

Note：Sync Adapter 框架會(huì)在一個(gè)后臺(tái)線程中執(zhí)行 onPerformSync() 方法，所以我們不需要配置后臺(tái)處理任務(wù)。

除了和同步相關(guān)的任務(wù)之外，我們還應(yīng)該嘗試將一些周期性的網(wǎng)絡(luò)相關(guān)的任務(wù)合并起來，并將它們添加到 onPerformSync() 中。將所有網(wǎng)絡(luò)任務(wù)集中到該方法內(nèi)處理，可以減少由啟動(dòng)和停止網(wǎng)絡(luò)接口所造成的電量損失。有關(guān)更多如何在進(jìn)行網(wǎng)絡(luò)訪問時(shí)更高效地使用電池方面的知識(shí)，可以閱讀：Transferring Data Without Draining the Battery，它描述了一些在數(shù)據(jù)傳輸代碼中可以包含的網(wǎng)絡(luò)訪問任務(wù)。

將 Sync Adapter 綁定到框架上

現(xiàn)在，我們已經(jīng)將數(shù)據(jù)傳輸代碼封裝在 Sync Adapter 組件中，但是我們必須讓框架可以訪問我們的代碼。為了做到這一點(diǎn)，我們需要?jiǎng)?chuàng)建一個(gè)綁定 Service，它將一個(gè)特殊的 Android Binder 對(duì)象從 Sync Adapter 組件傳遞給框架。有了這一 Binder 對(duì)象，框架就可以調(diào)用 onPerformSync() 方法并將數(shù)據(jù)傳遞給它。

在服務(wù)的 onCreate() 方法中將我們的 Sync Adapter 組件實(shí)例化為一個(gè)單例。通過在 onCreate() 方法中實(shí)例化該組件，我們可以推遲到服務(wù)啟動(dòng)后再創(chuàng)建它，這會(huì)在框架第一次嘗試執(zhí)行數(shù)據(jù)傳輸時(shí)發(fā)生。我們需要通過一種線程安全的方法來實(shí)例化組件，以防止 Sync Adapter 框架在響應(yīng)觸發(fā)和調(diào)度時(shí)，形成含有多個(gè) Sync Adapter 執(zhí)行的隊(duì)列。

下面的代碼片段展示了我們應(yīng)該如何實(shí)現(xiàn)一個(gè)綁定 Service 的類，實(shí)例化我們的 Sync Adapter 組件，并獲取 Android Binder 對(duì)象：

package com.example.android.syncadapter;
/**
 * Define a Service that returns an 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：要看更多 Sync Adapter 綁定服務(wù)的例子，可以閱讀樣例代碼。

添加框架所需的賬戶

Sync Adapter 框架需要每個(gè) Sync Adapter 擁有一個(gè)賬戶類型。在創(chuàng)建 Stub 授權(quán)器章節(jié)中，我們已經(jīng)聲明了賬戶類型的值?，F(xiàn)在我們需要在 Android 系統(tǒng)中配置該賬戶類型。要配置賬戶類型，通過調(diào)用 addAccountExplicitly() 添加一個(gè)使用其賬戶類型的虛擬賬戶。

調(diào)用該方法最合適的地方是在應(yīng)用的啟動(dòng) Activity 的 onCreate() 方法中。如下面的代碼樣例所示：

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.
             */
        }
    }
    ...
}

添加 Sync Adapter 的元數(shù)據(jù)文件

要將我們的 Sync Adapter 組件集成到框架中，我們需要向框架提供描述組件的元數(shù)據(jù)，以及額外的標(biāo)識(shí)信息。元數(shù)據(jù)指定了我們?yōu)?Sync Adapter 所創(chuàng)建的賬戶類型，聲明了一個(gè)和應(yīng)用相關(guān)聯(lián)的 Content Provider Authority，對(duì)和 Sync Adapter 相關(guān)的一部分系統(tǒng)用戶接口進(jìn)行控制，同時(shí)還聲明了其它同步相關(guān)的標(biāo)識(shí)。在我們項(xiàng)目的 /res/xml/ 目錄下的一個(gè)特定文件內(nèi)聲明這一元數(shù)據(jù)，我們可以為這個(gè)文件命名，不過通常來說我們將其命名為 syncadapter.xml。

在這一文件中包含了一個(gè) XML 標(biāo)簽 <sync-adapter>，它包含了下列的屬性字段：

android:contentAuthority

Content Provider 的 URI Authority。如果我們?cè)谇耙还?jié)課程中為應(yīng)用創(chuàng)建了一個(gè) Stub Content Provider，那么請(qǐng)使用在 manifest 清單文件中添加在 <provider> 標(biāo)簽內(nèi)的 android:authorities 屬性值。這一屬性的更多細(xì)節(jié)在本章后續(xù)章節(jié)中有更多的介紹。

如果我們正使用 Sync Adapter 將數(shù)據(jù)從 Content Provider 傳輸?shù)椒?wù)器上，該屬性的值應(yīng)該和數(shù)據(jù)的 Content URI Authority 保持一致。這個(gè)值也是我們?cè)?manifest 清單文件中添加在 <provider> 標(biāo)簽內(nèi) android:authorities 屬性的值。

android:accountType

Sync Adapter 框架所需要的賬戶類型。這個(gè)值必須和我們所創(chuàng)建的驗(yàn)證器元數(shù)據(jù)文件內(nèi)所提供的賬戶類型一致（詳細(xì)內(nèi)容可以閱讀：創(chuàng)建 Stub 授權(quán)器）。這也是在上一節(jié)的代碼片段中。常量 ACCOUNT_TYPE 的值。

配置相關(guān)屬性

android:userVisible

該屬性設(shè)置 Sync Adapter 框架的賬戶類型是否可見。默認(rèn)地，和賬戶類型相關(guān)聯(lián)的賬戶圖標(biāo)和標(biāo)簽在系統(tǒng)設(shè)置的賬戶選項(xiàng)中可以看見，所以我們應(yīng)該將 Sync Adapter 設(shè)置為對(duì)用戶不可見（除非我們確實(shí)擁有一個(gè)賬戶類型或者域名或者它們可以輕松地和我們的應(yīng)用相關(guān)聯(lián)）。如果我們將賬戶類型設(shè)置為不可見，那么我們?nèi)匀豢梢栽试S用戶通過一個(gè) Activity 中的用戶接口來控制 Sync Adapter。

android:supportsUploading

允許我們將數(shù)據(jù)上傳到云。如果應(yīng)用僅僅下載數(shù)據(jù)，那么請(qǐng)將該屬性設(shè)置為 false。

android:allowParallelSyncs

允許多個(gè) Sync Adapter 組件的實(shí)例同時(shí)運(yùn)行。如果應(yīng)用支持多個(gè)用戶賬戶并且我們希望多個(gè)用戶并行地傳輸數(shù)據(jù)，那么可以使用該特性。如果我們從不執(zhí)行多個(gè)數(shù)據(jù)傳輸，那么這個(gè)選項(xiàng)是沒用的。

android:isAlwaysSyncable

指明 Sync Adapter 框架可以在任何我們指定的時(shí)間運(yùn)行 Sync Adapter。如果我們希望通過代碼來控制 Sync Adapter 的運(yùn)行時(shí)機(jī)，請(qǐng)將該屬性設(shè)置為 false。然后調(diào)用 requestSync() 來運(yùn)行 Sync Adapter。要學(xué)習(xí)更多關(guān)于運(yùn)行 Sync Adapter 的知識(shí)，可以閱讀：執(zhí)行 Sync Adapter。

下面的代碼展示了應(yīng)該如何通過 XML 配置一個(gè)使用單個(gè)虛擬賬戶，并且只執(zhí)行下載的 Sync Adapter：

<?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"/>

在 Manifest 清單文件中聲明 Sync Adapter

一旦我們將 Sync Adapter 組件集成到應(yīng)用中，我們需要聲明相關(guān)的權(quán)限來使用它，并且還需要聲明我們所添加的綁定 Service。

由于 Sync Adapter 組件會(huì)運(yùn)行設(shè)備與網(wǎng)絡(luò)之間傳輸數(shù)據(jù)的代碼，所以我們需要請(qǐng)求使用網(wǎng)絡(luò)的權(quán)限。同時(shí)，我們的應(yīng)用還需要讀寫 Sync Adapter 配置信息的權(quán)限，這樣我們才能通過應(yīng)用中的其它組件去控制 Sync Adapter。另外，我們還需要一個(gè)特殊的權(quán)限，來允許應(yīng)用使用我們?cè)?a href="create-authenticator.html">創(chuàng)建 Stub 授權(quán)器中所創(chuàng)建的授權(quán)器組件。

要請(qǐng)求這些權(quán)限，將下列內(nèi)容添加到應(yīng)用 manifest 清單文件中，并作為 <manifest> 標(biāo)簽的子標(biāo)簽：

android.permission.INTERNET

允許 Sync Adapter 訪問網(wǎng)絡(luò)，使得它可以從設(shè)備下載和上傳數(shù)據(jù)到服務(wù)器。如果之前已經(jīng)請(qǐng)求了該權(quán)限，那么就不需要重復(fù)請(qǐng)求了。

android.permission.READ_SYNC_SETTINGS

允許應(yīng)用讀取當(dāng)前的 Sync Adapter 配置。例如，我們需要該權(quán)限來調(diào)用 getIsSyncable()。

android.permission.WRITE_SYNC_SETTINGS

允許我們的應(yīng)用 對(duì)Sync Adapter 的配置進(jìn)行控制。我們需要這一權(quán)限來通過 addPeriodicSync() 方法設(shè)置執(zhí)行同步的時(shí)間間隔。另外，調(diào)用 requestSync() 方法不需要用到該權(quán)限。更多信息可以閱讀：執(zhí)行 Sync Adapter。

android.permission.AUTHENTICATE_ACCOUNTS

允許我們使用在創(chuàng)建 Stub 授權(quán)器中所創(chuàng)建的驗(yàn)證器組件。

下面的代碼片段展示了如何添加這些權(quán)限：

<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>

最后，要聲明框架用來和 Sync Adapter 進(jìn)行交互的綁定 Service，添加下列的 XML 代碼到應(yīng)用 manifest 清單文件中，作為 <application> 標(biāo)簽的子標(biāo)簽：

        <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>

<intent-filter> 標(biāo)簽配置了一個(gè)過濾器，它會(huì)被帶有 android.content.SyncAdapter 這一 Action 的 Intent 所觸發(fā)，該 Intent 一般是由系統(tǒng)為了運(yùn)行 Sync Adapter 而發(fā)出的。當(dāng)過濾器被觸發(fā)后，系統(tǒng)會(huì)啟動(dòng)我們所創(chuàng)建的綁定服務(wù)，在本例中它叫做 SyncService。屬性 android:exported="true" 允許我們應(yīng)用之外的其它進(jìn)程（包括系統(tǒng)）訪問這一 Service。屬性 android:process=":sync" 告訴系統(tǒng)應(yīng)該在一個(gè)全局共享的，且名字叫做 sync 的進(jìn)程內(nèi)運(yùn)行該 Service。如果我們的應(yīng)用中有多個(gè) Sync Adapter，那么它們可以共享該進(jìn)程，這有助于減少開銷。

<meta-data> 標(biāo)簽提供了我們之前為 Sync Adapter 所創(chuàng)建的元數(shù)據(jù) XML 文件的文件名。屬性 android:name 指出這一元數(shù)據(jù)是針對(duì)于 Sync Adapter 框架的。而 android:resource 標(biāo)簽則指定了元數(shù)據(jù)文件的名稱。

現(xiàn)在我們已經(jīng)為 Sync Adapter 準(zhǔn)備好所有相關(guān)的組件了。下一節(jié)課將講授如何讓 Sync Adapter 框架運(yùn)行 Sync Adapter。要實(shí)現(xiàn)這一點(diǎn)，既可以通過響應(yīng)一個(gè)事件的方式，也可以通過執(zhí)行一個(gè)周期性任務(wù)的方式。