This document provides an overview and primer on sync adapters in Android. It discusses who Kiana is and her background. It then covers the key components of sync adapters including configuration with XML resources, using content providers to manage the data, handling authentication with account managers, and how the sync manager and sync adapters perform synchronization. The document aims to explain the different pieces and how they fit together to enable syncing data between a remote source and Android devices.

1. A PRIMER TO
SYNC ADAPTERS
Kiana Tennyson
mdevcon
Tuschinski Theater
March 2013

2. OVERVIEW
v Who is Kiana?
v SyncAdapter Use Cases
v The Big Picture
v Configuration
v Authorization, Content, Synchronization
v Wrap up/Questions

3. WHO’S KIANA?
v Software Developer
v Professional background working on web portals
v Work at Manheim, wholesale vehicle auction company
v Customer facing applications
• Web portal (www.manheim.com) Ruby, Java, JS
• iOS app
• Android app

4. SYNC ADAPTERS ARE…?
v Share data between a remote data source and an Android
device
v Android OS provides plug-in architecture that takes care of:
• Coordinating network availability with syncing all datasources
• Scheduling synchronization/Handling stopped processes
• Accommodating user preferences when syncing
• Handling network interruptions

5. TOUGH PARTS
v Good news! Writing a Custom SyncAdapter is actually easy!
v Bad news. There are potentially tough parts:
• Authentication Handling
• (Custom) Content Provider
• Data Handling
v Defined by business rules

6. BEST USE CASES
Application that…
v Requires authentication step to connect to remote
datasource
v Potentially could use a built-in ContentProvider
• All providers found in android.provider package
v Application Suite backed by custom ContentProvider

7. !(BEST USE CASES)
v Anything that DOES NOT require a login
v Any source that provides an RSS feed
• Typically public data sources like news/media sites
• Write a parser that reads the feed only when the user wants it
• SyncAdapter not necessary to write to the ContentProvider
v If Service does not constantly need to run in the
background
• User has limited battery power, code with this in mind

8. A Primer to SyncAdapters
CONFIGURATION

9. THE BIG PICTURE
AccountManager SyncManager ContentProvider
• Requires • Uses Account • Holds the data
Authentication List as a basis for • Called in
Service to add it’s Sync List onPerformSync()
Account • Requires Sync
• Adds Account to Service to start
Account List data syncs

10. AUTHENTICATION
v Write an AuthActivity
• serves UI for user to enter account info
• Write it to complete the authorization process
v Write an Authenticator
• MUST extend AbstractAccountAuthenticator
• Returns the AuthActivity in a Bundle object
v Write an Authentication Service
• MUST extend Service
• onBind return IBinder for the Authenticator

11. SYNCHRONIZATION
v Write a SyncAdapter
• MUST extend AbstractThreadedSyncAdapter
• Overwrite onPerformSync()
v Write a Sync Service
• MUST extend Service
• Allow creation of ONE SyncAdapter
• onBind returns a IBinder for SyncAdapter

12. RESOURCE XMLS
v Provide configuration info
v Map account type to objects
• SyncAdapter and Authenticator are connected via
android:accountType
v Map content authority to SyncAdapter

13. RESOURCE XMLS
<?xml version="1.0" encoding="utf-8"?>!
<account-authenticator xmlns:android="http://
!schemas.android.com/apk/res/android”!
android:accountType=”your.uniquename.here"!
android:icon="@drawable/icon"!
android:smallIcon="@drawable/icon"!
android:label="@string/label"!
/>!

14. Add Account
v Notice result of android:icon
v Green lights – Account added
v Gray lights – Account not added
v Clicking one launches Auth
Activity interface

15. RESOURCE XMLS
<?xml version="1.0" encoding="utf-8"?>!
<sync-adapter xmlns:android="http://
!schemas.android.com/apk/res/android”!
android:contentAuthority="com.android.contacts"!
android:accountType="your.uniquename.here"!
android:supportsUploading="false"!
android:userVisible="true"!
/>!

16. MANIFEST
v Several appropriate permissions
v Declare AuthenticationService with <service> tag
• Intent filter: “android.accounts.AccountAuthenticator”
• Meta-data tag points AccountAuthenticator to xml resource file
v Declare SyncService with <service> tag
• Intent filter: “android.content.SyncAdapter”
• Meta-data tag points SyncAdapter to xml resource file
• Other Meta-data tag defines custom MIME-types
v Declare AuthActivity (no Intent filter necessary)

17. MANIFEST.XML
<service android:name=".authenticator.AuthenticationService”
!android:exported="true”>!
<intent-filter>!
<action android:name="android.accounts.AccountAuthenticator" />!
</intent-filter>!
<meta-data android:name="android.accounts.AccountAuthenticator”!
!android:resource="@xml/authenticator" />!
</service>!
<service android:name=".syncadapter.SyncService” android:exported="true">!
<intent-filter>!
<action android:name="android.content.SyncAdapter" />!
</intent-filter>!
<meta-data android:name="android.content.SyncAdapter”!
!android:resource="@xml/syncadapter" />!
<meta-data android:name="android.provider.CONTACTS_STRUCTURE”!
!android:resource="@xml/contacts" />!
</service>!

18. WHY SERVICES?
v SyncAdapter is bound to a service, Authentication is bound to a
service… but why?
v SyncManager finds all syncAdapters via a SyncAdaptersCache.
v AccountManager finds all Accounts via AccountAuthenticatorCache
v RegisteredServicesCache
• Reads the XML files created (account-authenticator and syncadapter)
• Generates service maps

19. CODE SUMMARY
v Create a syncadapter.xml file
v Create an authenticator.xml file
v Add an authentication <service> to manifest
v Add a sync <service> to manifest
v Add correct permissions to manifest
v Write some java… but what does any of this mean?

20. A Primer to SyncAdapters
THE DATA

21. ACCESSING CONTENT
• SharedPreferences
Data Storage • External Storage
• SQLLiteDatabase
ContentProvider
ContentProviderClient
ContentResolver
Context
Android Application(s)
The Device User

22. CONTENT PROVIDER
v Manages central repository of data.
v SyncAdapters wouldn’t exist without ContentProviders
• SyncAdapter mentioned in ContentProvider section of API
Guide
v Built in ContentProviders contain a SyncState table
• Use to store sync state, meta-data or any sync related data
v Sync related columns in other tables:
• DIRTY, VERSION, SOURCE_ID

23. IMPORTANT COLUMNS
v DIRTY (local modifications)
• Indicates data row has been changed locally since last sync.
• When SyncAdapter adds/updates a row, append
“CALLER_IS_SYNCADAPTER” to Content URI
v VERSION
• Incremented by Provider whenever the data row is changed.
• High-water marking (aka lastSyncState)
v SOURCE_ID
• Unique ID for data row (primary key on the remote datasource)
• If set to null, indicates to SyncAdapter to create new row on remote
source

24. CUSTOM
CONTENT PROVIDER
v What properties make the built-in ContentProviders
“syncable”?
• Extra “For Sync use only” table that holds metadata
• “CALLER_IS_SYNCADAPTER” query param
• Use of “high-water-mark” is essential
v These properties should be applied to Custom SyncAdapter

25. CONTENT RESOLVER VS
CONTENTPROVIDER CLIENT
ContentResolver ContentProviderClient
v Thread safe v Not thread safe
v Many calls to many v Repeated calls to same CA
ContentAuthorities (CA) v Cheaper call (one CA lookup)
v Expensive call (Many CA lookups) v You MUST call release() to avoid
v Resolver contains a Client memory leak

26. CONTENTPROVIDER
CLIENT
v Part of onPerformSync() method signature.
v Not thread safe, so be careful with usage
• Utilize locking strategies, ensure no outside services are
performing activities on sync-candidate data
v Android Sample project uses threadsafe ContentResolver
via a Manager

27. CONTENT RESOLVER
v Do I really need this? Your choice.
• ContentResolvers query the ContentProvider
• Use it to CRUD data inside syncAdapter.onPerformSync();
• SampleSyncAdapter uses the ContentResolver by way of it’s
ContactsManager class, because it performs batch operations
v Retrieve it using: context.getContentResolver();
v However, there are other ways to access the data

28. DATA CONSIDERATIONS
v Determine structure of serialized/transmitted data
• Using json? xml? yaml?
• What does a single row (data unit) look like?
v How does the server parse and save the transmitted data?
• Likely defined by business limitations.
v How does the device parse/save the data?
• ContentProviderClient or ContentResolver (batch ops)

29. A Primer to SyncAdapters
AUTHENTICATION

30. ACCOUNT
v Account object contains an Account name and Account type.
• Note, the Account object does NOT contain a password
• Example: user has multiple twitter accounts
v AccountManager maps an Account object to it’s “password”
v Recommended strategy: store Account and authToken on device
• SampleSyncAdapter project stores password (possible human error)
v SyncManager can only schedule syncs per Account

31. ACCOUNT MANAGER
v Contains centralized registry of user’s online accounts
v Used to determine list of data sources to be synced
• AccountManager provides list of Accounts
• SyncManager grabs the list of Accounts for syncing
v AccountAuthenticatorCache maps accountType to objects
extending AbstractAccountAuthenticator
v Android Component; you don’t write this

32. AUTHENTICATION
v User chooses to Add an Account
• List compiled from array of allowable account types
v System chooses Authenticator based on
“android:accountType”
• Binds to a Service which returns the Authenticator’s IBinder
v Authenticator’s overridden addAccount() method is called
• Ultimately the Login UI displays, new Account is created

33. AUTHENTICATOR
v Allows developer to implement authentication
• Per remote service
v Must extend AbstractAccountAuthenticator
• Responds to an intent “android.accounts.AccountAuthenticator”
advertised by the AccountManager for it’s accountType only.
v Authentication Service returns a Binder to your implemented
AbstractAccountAuthenticator
v addAccount() returns bundle with intent containing Activity

34. ADD ACCOUNT
Sample SyncAdapter Activity Example Activity

35. A Primer to SyncAdapters
THE SYNC

36. SYNCMANAGER
v Responsible for scheduling, cancelling syncs.
• Maintains a list of active syncs (mActiveSyncContext)
v Sync handling strategy very tightly coupled to Accounts
• Account is part of most SyncManager methods
v How do the SyncHandler and Account interact?
• SyncHandler receives a message containing an
ActiveSyncContext. ActiveSyncContext contains all
information about the sync that needs to begin including the
Account.

37. SYNCHRONIZATION
v SyncManager contains ONE SyncHandler
v SyncHandler’s job: receive/handle sync operation messages
• On receiving a Connection Message, calls startSync for the
syncAdapter in question
• startSync() spins up a new SyncThread
• The method onPerformSync() that was implemented is
invoked when run() is invoked on the thread

38. SYNC ADAPTER
v Where the main party happens. The method onPerformSync()
gets called within a syncThread.run()
v Make use of the DIRTY/VERSION/SOURCE_ID rows
v Instantiate like any class.
• However, create only one for thread safety.

39. ONPERFORMSYNC()
v What should I do in the onPerformSync() method?
v Merge remote data with local data
• DIRTY/VERSION/SOURCE_ID columns
v Use business rules to determine order of operations
• Whether local data overwrites remote data or vice versa
v Implement a remote connection strategy to access remote
data

40. DEV TOOLS

41. WRAP UP
v We learned…
• What SyncAdapters are
• Set up
• Content (ContentProvider/data characteristics)
• Authorization (Accounts, Account Management)
• Synchronization (SyncManager, SyncService)
• Debugging/Dev Tools

42. A Primer to SyncAdapters
QUESTIONS?