原文:http://developer.android.com/training/sync-adapters/creating-sync-adapter.html
設備和服務器之間執行數據傳輸的代碼會封裝在應用的 Sync Adapter 組件中。Sync Adapter 框架會基于我們的調度和觸發操作，運行 Sync Adapter 組件中的代碼。要將同步適配組件添加到應用當中，我們需要添加下列部件：
Sync Adapter 類
將我們的數據傳輸代碼封裝到一個與 Sync Adapter 框架兼容的接口當中。
綁定Service
通過一個綁定服務，允許 Sync Adapter 框架運行 Sync Adapter 類中的代碼。
Sync Adapter 的 XML 元數據文件
該文件包含了有關 Sync Adapter 的信息。框架會根據該文件確定應該如何加載并調度數據傳輸任務。
應用 manifest 清單文件的聲明
需要在應用的 manifest 清單文件中聲明綁定服務；同時還需要指出 Sync Adapter 的元數據。
這節課將會向我們展示如何定義他們。
創建一個 Sync Adapter 類
在這部分課程中，我們將會學習如何創建封裝了數據傳輸代碼的 Sync Adapter 類。創建該類需要繼承 Sync Adapter 的基類；為該類定義構造函數；以及實現相關的方法。在這些方法中，我們定義數據傳輸任務。
繼承 Sync Adapter 基類：AbstractThreadedSyncAdapter
要創建 Sync Adapter 組件，首先繼承AbstractThreadedSyncAdapter，然后編寫它的構造函數。與使用Activity.onCreate()配置 Activity 時一樣，每次我們重新創建 Sync Adapter 組件的時候，使用構造函數執行相關的配置。例如，如果我們的應用使用一個 Content Provider 來存儲數據，那么使用構造函數來獲取一個ContentResolver實例。由于從 Android 3.0 開始添加了第二種形式的構造函數，來支持parallelSyncs參數，所以我們需要創建兩種形式的構造函數來保證兼容性。
Note：Sync Adapter 框架是設計成和 Sync Adapter 組件的單例一起工作的。實例化 Sync Adapter 組件的更多細節，會在后面的章節中展開。
下面的代碼展示了如何實現AbstractThreadedSyncAdapter和它的構造函數：
/**
* Handle the transfer of data between a server and an
* app, using the Android sync adapter framework.
*/publicclassSyncAdapterextendsAbstractThreadedSyncAdapter{? ? ...// Global variables// Define a variable to contain a content resolver instanceContentResolver mContentResolver;/**
* Set up the sync adapter
*/publicSyncAdapter(Context context,booleanautoInitialize){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
*/publicSyncAdapter(? ? ? ? ? ? Context context,booleanautoInitialize,booleanallowParallelSyncs){super(context, autoInitialize, allowParallelSyncs);/*
* If your app uses a content resolver, get an instance of it
* from the incoming Context
*/mContentResolver = context.getContentResolver();? ? ? ? ...? ? }
在 onPerformSync() 中添加數據傳輸代碼
Sync Adapter 組件并不會自動地執行數據傳輸。它對我們的數據傳輸代碼進行封裝，使得 Sync Adapter 框架可以在后臺執行數據傳輸，而不會牽連到我們的應用。當框架準備同步我們的應用數據時，它會調用我們所實現的onPerformSync()方法。
為了便于將數據從應用程序轉移到 Sync Adapter 組件中，Sync Adapter 框架調用onPerformSync()，它具有下面的參數：
Account
該Account對象與觸發 Sync Adapter 的事件相關聯。如果服務端不需要使用賬戶，那么我們不需要使用這個對象內的信息。
Extras
一個 Bundle 對象，它包含了一些標識，這些標識由觸發 Sync Adapter 的事件所發送。
Authority
系統中某個 Content Provider 的 Authority。我們的應用必須要有訪問它的權限。通常，該 Authority 對應于應用的 Content Provider。
Content provider client
ContentProviderClient針對于由Authority參數所指向的Content Provider。ContentProviderClient是一個 Content Provider 的輕量級共有接口。它的基本功能和ContentResolver一樣。如果我們正在使用 Content Provider 來存儲應用數據，那么我們可以利用它連接 Content Provider。反之，則將其忽略。
Sync result
一個SyncResult對象，我們可以使用它將信息發送給 Sync Adapter 框架。
下面的代碼片段展示了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.
*/@OverridepublicvoidonPerformSync(
Account account,
Bundle extras,
String authority,
ContentProviderClient provider,
SyncResult syncResult){/*
* Put the data transfer code here.
*/...? ? }
雖然實際的onPerformSync()實現是要根據應用數據的同步需求以及服務器的連接協議來制定，但是我們的實現只需要執行一些常規任務：
連接到一個服務器
盡管我們可以假定在開始傳輸數據時，已經獲取到了網絡連接，但是 Sync Adapter 框架并不會自動地連接到一個服務器。
下載和上傳數據
Sync Adapter 不會自動執行數據傳輸。如果我們想要從服務器下載數據并將它存儲到 Content Provider 中，我們必須提供請求數據，下載數據和將數據插入到 Provider 中的代碼。類似地，如果我們想把數據發送到服務器，我們需要從一個文件，數據庫或者 Provider 中讀取數據，并且發送必需的上傳請求。同時我們還需要處理在執行數據傳輸時所發生的網絡錯誤。
處理數據沖突或者確定當前數據的狀態
Sync Adapter 不會自動地解決服務器數據與設備數據之間的沖突。同時，它也不會自動檢測服務器上的數據是否比設備上的數據要新，反之亦然。因此，我們必須自己提供處理這些狀況的算法。
清理
在數據傳輸的尾聲，記得要關閉網絡連接，清除臨時文件和緩存。
Note：Sync Adapter 框架會在一個后臺線程中執行onPerformSync()方法，所以我們不需要配置后臺處理任務。
除了和同步相關的任務之外，我們還應該嘗試將一些周期性的網絡相關的任務合并起來，并將它們添加到onPerformSync()中。將所有網絡任務集中到該方法內處理，可以減少由啟動和停止網絡接口所造成的電量損失。有關更多如何在進行網絡訪問時更高效地使用電池方面的知識，可以閱讀：Transferring Data Without Draining the Battery，它描述了一些在數據傳輸代碼中可以包含的網絡訪問任務。
將 Sync Adapter 綁定到框架上
現在，我們已經將數據傳輸代碼封裝在 Sync Adapter 組件中，但是我們必須讓框架可以訪問我們的代碼。為了做到這一點，我們需要創建一個綁定Service，它將一個特殊的 Android Binder 對象從 Sync Adapter 組件傳遞給框架。有了這一 Binder 對象，框架就可以調用onPerformSync()方法并將數據傳遞給它。
在服務的onCreate()方法中將我們的 Sync Adapter 組件實例化為一個單例。通過在onCreate()方法中實例化該組件，我們可以推遲到服務啟動后再創建它，這會在框架第一次嘗試執行數據傳輸時發生。我們需要通過一種線程安全的方法來實例化組件，以防止 Sync Adapter 框架在響應觸發和調度時，形成含有多個 Sync Adapter 執行的隊列。
下面的代碼片段展示了我們應該如何實現一個綁定Service的類，實例化我們的 Sync Adapter 組件，并獲取 Android Binder 對象：
packagecom.example.android.syncadapter;/**
* Define a Service that returns an IBinder for the
* sync adapter class, allowing the sync adapter framework to call
* onPerformSync().
*/publicclassSyncServiceextendsService{// Storage for an instance of the sync adapterprivatestaticSyncAdapter sSyncAdapter =null;// Object to use as a thread-safe lockprivatestaticfinalObject sSyncAdapterLock =newObject();/*
* Instantiate the sync adapter object.
*/@OverridepublicvoidonCreate(){/*
* Create the sync adapter as a singleton.
* Set the sync adapter as syncable
* Disallow parallel syncs
*/synchronized(sSyncAdapterLock) {if(sSyncAdapter ==null) {? ? ? ? ? ? ? ? sSyncAdapter =newSyncAdapter(getApplicationContext(),true);? ? ? ? ? ? }? ? ? ? }? ? }/**
* Return an object that allows the system to invoke
* the sync adapter.
*
*/@OverridepublicIBinderonBind(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()
*/returnsSyncAdapter.getSyncAdapterBinder();? ? }}
Note：要看更多 Sync Adapter 綁定服務的例子，可以閱讀樣例代碼。
添加框架所需的賬戶
Sync Adapter 框架需要每個 Sync Adapter 擁有一個賬戶類型。在創建 Stub 授權器章節中，我們已經聲明了賬戶類型的值。現在我們需要在 Android 系統中配置該賬戶類型。要配置賬戶類型，通過調用addAccountExplicitly()添加一個使用其賬戶類型的虛擬賬戶。
調用該方法最合適的地方是在應用的啟動 Activity 的onCreate()方法中。如下面的代碼樣例所示：
publicclassMainActivityextendsFragmentActivity{? ? ...? ? ...// Constants// The authority for the sync adapter's content providerpublicstaticfinalString AUTHORITY ="com.example.android.datasync.provider"http:// An account type, in the form of a domain namepublicstaticfinalString ACCOUNT_TYPE ="example.com";// The account namepublicstaticfinalString ACCOUNT ="dummyaccount";// Instance fieldsAccount mAccount;? ? ...@OverrideprotectedvoidonCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);? ? ? ? ...// Create the dummy accountmAccount = CreateSyncAccount(this);? ? ? ? ...? ? }? ? .../**? ? * Create a new dummy account for the sync adapter? ? *? ? *@paramcontext The application context? ? */publicstaticAccountCreateSyncAccount(Context context){// Create the account type and default accountAccount newAccount =newAccount(? ? ? ? ? ? ? ? ACCOUNT, ACCOUNT_TYPE);// Get an instance of the Android account managerAccountManager 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 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 的元數據文件
要將我們的 Sync Adapter 組件集成到框架中，我們需要向框架提供描述組件的元數據，以及額外的標識信息。元數據指定了我們為 Sync Adapter 所創建的賬戶類型，聲明了一個和應用相關聯的 Content Provider Authority，對和 Sync Adapter 相關的一部分系統用戶接口進行控制，同時還聲明了其它同步相關的標識。在我們項目的/res/xml/目錄下的一個特定文件內聲明這一元數據，我們可以為這個文件命名，不過通常來說我們將其命名為syncadapter.xml。
在這一文件中包含了一個 XML 標簽，它包含了下列的屬性字段：
android:contentAuthority
Content Provider 的 URI Authority。如果我們在前一節課程中為應用創建了一個 Stub Content Provider，那么請使用在 manifest 清單文件中添加在標簽內的android:authorities屬性值。這一屬性的更多細節在本章后續章節中有更多的介紹。
如果我們正使用 Sync Adapter 將數據從 Content Provider 傳輸到服務器上，該屬性的值應該和數據的 Content URI Authority 保持一致。這個值也是我們在 manifest 清單文件中添加在標簽內android:authorities屬性的值。
android:accountType
Sync Adapter 框架所需要的賬戶類型。這個值必須和我們所創建的驗證器元數據文件內所提供的賬戶類型一致（詳細內容可以閱讀：創建 Stub 授權器）。這也是在上一節的代碼片段中。常量ACCOUNT_TYPE的值。
配置相關屬性
android:userVisible
該屬性設置 Sync Adapter 框架的賬戶類型是否可見。默認地，和賬戶類型相關聯的賬戶圖標和標簽在系統設置的賬戶選項中可以看見，所以我們應該將 Sync Adapter 設置為對用戶不可見（除非我們確實擁有一個賬戶類型或者域名或者它們可以輕松地和我們的應用相關聯）。如果我們將賬戶類型設置為不可見，那么我們仍然可以允許用戶通過一個 Activity 中的用戶接口來控制 Sync Adapter。
android:supportsUploading
允許我們將數據上傳到云。如果應用僅僅下載數據，那么請將該屬性設置為false。
android:allowParallelSyncs
允許多個 Sync Adapter 組件的實例同時運行。如果應用支持多個用戶賬戶并且我們希望多個用戶并行地傳輸數據，那么可以使用該特性。如果我們從不執行多個數據傳輸，那么這個選項是沒用的。
android:isAlwaysSyncable
指明 Sync Adapter 框架可以在任何我們指定的時間運行 Sync Adapter。如果我們希望通過代碼來控制 Sync Adapter 的運行時機，請將該屬性設置為false。然后調用requestSync()來運行 Sync Adapter。要學習更多關于運行 Sync Adapter 的知識，可以閱讀：執行 Sync Adapter。
下面的代碼展示了應該如何通過 XML 配置一個使用單個虛擬賬戶，并且只執行下載的 Sync Adapter：
在 Manifest 清單文件中聲明 Sync Adapter
一旦我們將 Sync Adapter 組件集成到應用中，我們需要聲明相關的權限來使用它，并且還需要聲明我們所添加的綁定Service。
由于 Sync Adapter 組件會運行設備與網絡之間傳輸數據的代碼，所以我們需要請求使用網絡的權限。同時，我們的應用還需要讀寫 Sync Adapter 配置信息的權限，這樣我們才能通過應用中的其它組件去控制 Sync Adapter。另外，我們還需要一個特殊的權限，來允許應用使用我們在創建 Stub 授權器中所創建的授權器組件。
要請求這些權限，將下列內容添加到應用 manifest 清單文件中，并作為標簽的子標簽：
允許 Sync Adapter 訪問網絡，使得它可以從設備下載和上傳數據到服務器。如果之前已經請求了該權限，那么就不需要重復請求了。
android.permission.READ_SYNC_SETTINGS
允許應用讀取當前的 Sync Adapter 配置。例如，我們需要該權限來調用getIsSyncable()。
android.permission.WRITE_SYNC_SETTINGS
允許我們的應用 對Sync Adapter 的配置進行控制。我們需要這一權限來通過addPeriodicSync()方法設置執行同步的時間間隔。另外，調用requestSync()方法不需要用到該權限。更多信息可以閱讀：執行 Sync Adapter。
android.permission.AUTHENTICATE_ACCOUNTS
允許我們使用在創建 Stub 授權器中所創建的驗證器組件。
下面的代碼片段展示了如何添加這些權限：
......
最后，要聲明框架用來和 Sync Adapter 進行交互的綁定Service，添加下列的 XML 代碼到應用 manifest 清單文件中，作為標簽的子標簽：
標簽配置了一個過濾器，它會被帶有android.content.SyncAdapter這一 Action 的 Intent 所觸發，該 Intent 一般是由系統為了運行 Sync Adapter 而發出的。當過濾器被觸發后，系統會啟動我們所創建的綁定服務，在本例中它叫做SyncService。屬性android:exported="true"允許我們應用之外的其它進程（包括系統）訪問這一Service。屬性android:process=":sync"告訴系統應該在一個全局共享的，且名字叫做sync的進程內運行該Service。如果我們的應用中有多個 Sync Adapter，那么它們可以共享該進程，這有助于減少開銷。
標簽提供了我們之前為 Sync Adapter 所創建的元數據 XML 文件的文件名。屬性android:name指出這一元數據是針對于 Sync Adapter 框架的。而android:resource標簽則指定了元數據文件的名稱。
現在我們已經為 Sync Adapter 準備好所有相關的組件了。下一節課將講授如何讓 Sync Adapter 框架運行 Sync Adapter。要實現這一點，既可以通過響應一個事件的方式，也可以通過執行一個周期性任務的方式。
