{"id":1037,"date":"2013-07-09T01:00:00","date_gmt":"2013-07-08T23:00:00","guid":{"rendered":"https:\/\/www.fussylogic.co.uk\/blog\/?p=1037"},"modified":"2014-10-10T12:08:30","modified_gmt":"2014-10-10T11:08:30","slug":"android-content-providers-and-synchronisation","status":"publish","type":"post","link":"https:\/\/www.fussylogic.co.uk\/blog\/?p=1037","title":{"rendered":"Android Content Providers and Synchronisation"},"content":{"rendered":"

Last<\/a> time<\/a> we looked at creating accounts for our own custom purposes on an Android device. Now we\u00e2\u20ac\u2122ve got an account, we\u00e2\u20ac\u2122d like to do something with it. This series of articles will cover using an account to regularly synchronise some state on an upstream server with state held on the Android device.<\/p>\n

Implementing synchronisation opens up a new can of worms for us. Synchronisation is done in tandem with Android\u00e2\u20ac\u2122s ContentProvider<\/code><\/a> subsystem. We\u00e2\u20ac\u2122ll have to implement one first before we can start on a synchroniser.<\/p>\n

Each content provider is registered with the system under a unique name. We tell the system about our provider by adding it to the manifest.<\/p>\n

    <provider<\/span> android:name=<\/span>".Provider"<\/span>\n        android:exported=<\/span>"false"<\/span>\n        android:authorities=<\/span>"@string\/provider_authority"<\/span>><\/span>\n    <\/provider><\/span><\/code><\/pre>\n
As usual we\u00e2\u20ac\u2122ll need this unique name in our code as well, so we\u00e2\u20ac\u2122ll use a string reference. I\u00e2\u20ac\u2122ve marked it as non-exported here as I don\u00e2\u20ac\u2122t want to offer the data stored in it outside this app.<\/p>\n
A real-world provider implementation will most likely use Android\u00e2\u20ac\u2122s built in SQLite. I\u00e2\u20ac\u2122d like to keep things uncomplicated here and avoid having to describe databases as well. Instead I\u00e2\u20ac\u2122m going to make as simple a provider as I can, and store a single field, say a street address. However, in being simple we\u00e2\u20ac\u2122ll see a facility that\u00e2\u20ac\u2122s hard to find described \u00e2\u20ac\u201c non-table-based providers.<\/p>\n
Let\u00e2\u20ac\u2122s begin then. A content provider uses URIs as the means of communicating the particular piece of data wanted. They are always of this form:<\/p>\n
content:\/\/PROVIDER_AUTHORITY\/per_provider_path<\/code><\/pre>\n
All providers use the \u00e2\u20ac\u0153content:\/\/<\/code>\u00e2\u20ac\u009d schema. PROVIDER_AUTHORITY<\/code> is the unique string we\u00e2\u20ac\u2122ve already seen, and is what Android uses to direct provider requests on the client side to the appropriate implementation on the server side. The path is, for the most part, the provider\u00e2\u20ac\u2122s choice.<\/p>\n
All content providers derive from the ContentProvider<\/code> class. Most of the URI decoding work is done by a convenience class from Android, UriMatcher<\/code>.<\/p>\n
public<\/span> class<\/span> Provider extends<\/span> ContentProvider {\n    public<\/span> static<\/span> final<\/span> String ADDRESS_FILENAME = "address.json"<\/span>\n    public<\/span> static<\/span> final<\/span> String PROVIDER_AUTHORITY = "uk.co.fussylogic.exampleprovider"<\/span>;\n    public<\/span> static<\/span> final<\/span> Uri PROVIDER_BASE_URI =\n        Uri.parse<\/span>(ContentResolver.SCHEME_CONTENT<\/span> + ":\/\/"<\/span> + PROVIDER_AUTHORITY);\n    public<\/span> static<\/span> final<\/span> Uri ADDRESS_URI = Uri.withAppendedPath<\/span>(PROVIDER_URI, "address"<\/span>);\n\n    \/\/ UriMatcher codes<\/span>\n    private<\/span> static<\/span> final<\/span> int<\/span> URIMATCH_ID_ADDRESS = 1<\/span>;\n\n    private<\/span> static<\/span> final<\/span> UriMatcher sURIMatcher = new<\/span> UriMatcher<\/span>(UriMatcher.NO_MATCH<\/span>);\n    static<\/span> {\n        sURIMatcher.addURI<\/span>(Constants.PROVIDER_AUTHORITY<\/span>, "address"<\/span>, URIMATCH_ID_ADDRESS);\n    }\n\n    @Override<\/span>\n    public<\/span> String getType<\/span>(Uri uri) {\n        \/\/ Pattern match the URI<\/span>\n        int<\/span> uriType = sURIMatcher.match<\/span>(uri);\n\n        switch<\/span> (uriType) {\n        case<\/span> URIMATCH_ID_ADDRESS:\n            return<\/span> "application\/json"<\/span>;\n        default<\/span>:\n            throw<\/span> new<\/span> IllegalArgumentException("Unknown URI: "<\/span> + uri);        \n        }\n    }\n\n    @Override<\/span>\n    public<\/span> Cursor query<\/span>(Uri uri, String[] projection, String selection,\n            String[] selectionArgs, String sortOrder) {\n        throw<\/span> new<\/span> IllegalArgumentException("Unknown URI: "<\/span> + uri);\n    }\n\n    @Override<\/span>\n    public<\/span> Uri insert<\/span>(Uri uri, ContentValues values) {\n        throw<\/span> new<\/span> IllegalArgumentException("Unknown\/unqueryable URI: "<\/span> + uri);\n    }\n\n    @Override<\/span>\n    public<\/span> int<\/span> delete<\/span>(Uri uri, String selection, String[] selectionArgs) {\n        throw<\/span> new<\/span> IllegalArgumentException("Unknown URI: "<\/span> + uri);\n    }\n\n    @Override<\/span>\n    public<\/span> int<\/span> update<\/span>(Uri uri, ContentValues values, String selection,\n            String[] selectionArgs) {\n        throw<\/span> new<\/span> IllegalArgumentException("Unknown URI: "<\/span> + uri);\n    }\n\n    @Override<\/span>\n    public<\/span> ParcelFileDescriptor openFile<\/span>(Uri uri, String mode)\n            throws<\/span> FileNotFoundException {\n        File fileName;\n        int<\/span> uriType = sURIMatcher.match<\/span>(uri);\n        switch<\/span> (uriType) {\n        case<\/span> URIMATCH_ID_ADDRESS:\n            fileName = new<\/span> File(getContext<\/span>().getFilesDir<\/span>(), ADDRESS_FILENAME);\n            break<\/span>;\n        default<\/span>:\n            throw<\/span> new<\/span> IllegalArgumentException("Non-file-based URI: "<\/span> + uri);\n        }\n\n        int<\/span> imode = 0<\/span>;\n        if<\/span> (mode.contains<\/span>("w"<\/span>)) imode |= ParcelFileDescriptor.MODE_WRITE_ONLY<\/span>\n                | ParcelFileDescriptor.MODE_CREATE<\/span>;\n        if<\/span> (mode.contains<\/span>("r"<\/span>)) imode |= ParcelFileDescriptor.MODE_READ_ONLY<\/span>;\n        if<\/span> (mode.contains<\/span>("+"<\/span>)) imode |= ParcelFileDescriptor.MODE_APPEND<\/span>;\n\n        if<\/span>( (imode & ParcelFileDescriptor.MODE_READ_ONLY<\/span>) != 0<\/span> && !fileName.exists<\/span>()) {\n            Log.d<\/span>(TAG, fileName + " doesn't exist ("<\/span> + imode + ")"<\/span>);\n        }\n\n        return<\/span> ParcelFileDescriptor.open<\/span>(fileName, imode);\n    }\n}<\/code><\/pre>\n
Normally ContentProvider<\/code> child classes wouldn\u00e2\u20ac\u2122t be so bare, and they certainly wouldn\u00e2\u20ac\u2122t leave all the key methods, query()<\/code>, insert()<\/code>, delete()<\/code>, and update()<\/code>, throwing exceptions. We\u00e2\u20ac\u2122re also only supporting a single URI so using UriMatcher<\/code> is overkill.<\/p>\n
This should be enough to let us read and write a file under the \/address<\/code> content URI; which is, in turn, enough to let us write a synchronisation service.<\/p>\n
As with our provider, we inform Android about the synchronisation service in the manifest. It\u00e2\u20ac\u2122s very similar to how we added an authenticator:<\/p>\n
    <service<\/span> android:name=<\/span>".SyncService"<\/span>\n        android:exported=<\/span>"false"<\/span>\n        android:label=<\/span>"@string\/app_name"<\/span> ><\/span>\n        <intent-filter><\/span>\n            <action<\/span> android:name=<\/span>"android.content.SyncAdapter"<\/span> \/><\/span>\n        <\/intent-filter><\/span>\n\n        <meta-data<\/span>\n            android:name=<\/span>"android.content.SyncAdapter"<\/span>\n            android:resource=<\/span>"@xml\/syncadapter"<\/span> \/><\/span>\n    <\/service><\/span><\/code><\/pre>\n
The presence of the SyncAdapter<\/code> intent filter makes Android go looking for the android.content.SyncAdapter<\/code> meta-data, which tells which XML file to find the synchroniser information.<\/p>\n
<?xml<\/span> version="1.0" encoding="utf-8"?><\/span>\n<sync-adapter<\/span> xmlns:android=<\/span>"http:\/\/schemas.android.com\/apk\/res\/android"<\/span>\n    android:contentAuthority=<\/span>"@string\/provider_authority"<\/span>\n    android:accountType=<\/span>"@string\/authenticator_account_type"<\/span>\n    android:userVisible=<\/span>"true"<\/span>\n    android:supportsUploading=<\/span>"true"<\/span>\n    android:allowParallelSyncs=<\/span>"false"<\/span>\n    android:isAlwaysSyncable=<\/span>"true"<\/span>\/><\/span><\/code><\/pre>\n
We\u00e2\u20ac\u2122ve already seen the setting for contentAuthority<\/code> above, and accountType<\/code> is the account we\u00e2\u20ac\u2122re syncing for \u00e2\u20ac\u201c this should match what we set in authenticator definition. The other fields are self-explanatory or easily looked up in the documents.<\/p>\n
The definition of our service goes along very similar lines to the authentication service.<\/p>\n
public<\/span> class<\/span> SyncService extends<\/span> Service {\n    \/\/ We keep one sync adapter for the service<\/span>\n    private<\/span> static<\/span> final<\/span> Object sSyncAdapterLock = new<\/span> Object();\n    private<\/span> static<\/span> SyncAdapter sSyncAdapter = null<\/span>;\n\n    @Override<\/span>\n    public<\/span> void<\/span> onCreate<\/span>() {\n        \/\/ The race condition we have to worry about is if multiple<\/span>\n        \/\/ SyncService's get created at the same time, and we create multiple<\/span>\n        \/\/ SyncAdapters.<\/span>\n        synchronized<\/span> (sSyncAdapterLock) {\n            if<\/span> (sSyncAdapter == null<\/span>) {\n                sSyncAdapter = new<\/span> SyncAdapter<\/span>(getApplicationContext<\/span>(), true<\/span>);\n            }\n        }\n    }\n\n    @Override<\/span>\n    public<\/span> IBinder onBind<\/span>(Intent intent) {\n        \/\/ What if onCreate() from the first thread is still running, but<\/span>\n        \/\/ hasn't created the SyncAdapter yet?  We should be locked here<\/span>\n        \/\/ too.<\/span>\n        synchronized<\/span> (sSyncAdapterLock) {\n            return<\/span> sSyncAdapter.getSyncAdapterBinder<\/span>();\n        }\n    }\n\n    \/\/ -------------------------------<\/span>\n\n    public<\/span> class<\/span> SyncAdapter extends<\/span> AbstractThreadedSyncAdapter {\n        protected<\/span> final<\/span> AccountManager mAccountManager;\n\n        public<\/span> SyncAdapter<\/span>(Context context, boolean<\/span> autoInitialize) {\n            super<\/span>(context, autoInitialize);\n            mContext = context;\n            mAccountManager = AccountManager.get<\/span>(context);\n        }\n\n        @Override<\/span>\n        public<\/span> void<\/span> onPerformSync<\/span>(Account account, Bundle extras,\n                String authority, ContentProviderClient provider,\n                SyncResult syncResult) {\n            try<\/span> {\n                performSync<\/span>(account, extras, authority, provider, syncResult);\n            } catch<\/span> (final<\/span> AuthenticatorException e) {\n                Log.e<\/span>(TAG, "Synchronise failed "<\/span>, e);\n                syncResult.stats<\/span>.numParseExceptions<\/span>++;\n            } catch<\/span> (final<\/span> OperationCanceledException e) {\n                Log.e<\/span>(TAG, "Synchronise failed "<\/span>, e);\n            } catch<\/span> (final<\/span> IOException e) {\n                Log.e<\/span>(TAG, "Synchronise failed "<\/span>, e);\n                syncResult.stats<\/span>.numIoExceptions<\/span>++;\n            } catch<\/span> (final<\/span> AuthenticationException e) {\n                Log.e<\/span>(TAG, "Synchronise failed "<\/span>, e);\n                syncResult.stats<\/span>.numAuthExceptions<\/span>++;\n            } catch<\/span> (final<\/span> JSONException e) {\n                Log.e<\/span>(TAG, "Synchronise failed "<\/span>, e);\n                syncResult.stats<\/span>.numParseExceptions<\/span>++;\n            } catch<\/span> (final<\/span> RuntimeException e) {\n                Log.e<\/span>(TAG, "Synchronise failed "<\/span>, e);\n                \/\/ Treat runtime exception as an I\/O error<\/span>\n                syncResult.stats<\/span>.numIoExceptions<\/span>++;\n            }\n        }\n\n        private<\/span> void<\/span> performSync<\/span>(Account account, Bundle extras,\n                String authority, ContentProviderClient provider,\n                SyncResult syncResult) throws<\/span> AuthenticatorException,\n                OperationCanceledException, IOException,\n                AuthenticationException, ParseException, JSONException {\n\n            \/\/ Use the account manager to request the AuthToken we'll need<\/span>\n            \/\/ to talk to our sample server.  If we don't have an AuthToken<\/span>\n            \/\/ yet, this could involve a round-trip to the server to request<\/span>\n            \/\/ an AuthToken.  We can block here as we're already in a non-UI<\/span>\n            \/\/ thread.<\/span>\n            final<\/span> String authToken = mAccountManager.blockingGetAuthToken<\/span>(\n                    account,\n                    getString<\/span>(R.string<\/span>.auth_token_type_default<\/span>),\n                    NOTIFY_AUTH_FAILURE);\n            if<\/span>( authToken == null<\/span> )\n                throw<\/span> new<\/span> AuthenticationException("No authentication token available for account, "<\/span>\n                        + account );\n\n            \/\/ --- Fetch from remote<\/span>\n            \/\/ NetworkCommunicator is application-specific, you would<\/span>\n            \/\/ implement it as you see fit<\/span>\n            NetworkCommunicator nc = new<\/span> NetworkCommunicator<\/span>();\n            nc.setAuthToken<\/span>(token);\n            JSONObject json = nc.fetchAddress<\/span>();\n\n            \/\/ --- Write to local<\/span>\n            \/\/ Get the appropriate URI as a constant from our provider<\/span>\n            Uri uri = Provider.ADDRESS_URI<\/span>;\n            OutputStream out = null<\/span>;\n            try<\/span> {\n                out = provider.openOutputStream<\/span>(uri, "w"<\/span>);\n            } catch<\/span> (FileNotFoundException e) {\n                Log.w<\/span>(TAG, "Content URI not available for writing, "<\/span> + uri);\n                throw<\/span> new<\/span> IOException(e);\n            }\n            out.write<\/span>(json.toString<\/span>().getBytes<\/span>(Charset.forName<\/span>("UTF-8"<\/span>)));\n            out.flush<\/span>();\n            out.close<\/span>();\n        }        \n    }\n}<\/code><\/pre>\n
This function is where we pull all the parts together. We fetch an authentication token from the account manager; we fetch from the remote service using that token; then write whatever we\u00e2\u20ac\u2122ve fetched to the provider.<\/p>\n
The actual mechanics of your synchronisation are obviously going to be application specific; and probably considerably more involved than this.<\/p>\n
Let\u00e2\u20ac\u2122s take a moment to notice what this tells us about Android. We have accounts (with a type that ties them to our authenticator), and within that account we can store multiple tokens, themselves each of a named type (again, as suits our application). Then we have content providers. A content provider is not (directly) tied to an account, it exists on its own. We tie a provider and an account (or rather an account type) together via a synchroniser. We could easily have multiple providers all holding different information from a single account. Each of those providers is tied to the account with its own synchronisation service. Go to your Android settings page and look in the accounts section. Open up the \u00e2\u20ac\u0153Google\u00e2\u20ac\u009d accounts, and pick one account. You are shown the \u00e2\u20ac\u0153sync\u00e2\u20ac\u009d page, mine has the following potential syncs:<\/p>\n