{"id":2006,"date":"2015-01-07T18:33:04","date_gmt":"2015-01-07T13:03:04","guid":{"rendered":"http:\/\/codetheory.in\/?p=2006"},"modified":"2015-01-31T00:26:43","modified_gmt":"2015-01-30T18:56:43","slug":"using-asyncqueryhandler-to-access-content-providers-asynchronously-in-android","status":"publish","type":"post","link":"https:\/\/codetheory.in\/using-asyncqueryhandler-to-access-content-providers-asynchronously-in-android\/","title":{"rendered":"Using AsyncQueryHandler to Access Content Providers Asynchronously in Android"},"content":{"rendered":"<p>In our previous posts we discussed <a href=\"http:\/\/codetheory.in\/working-sqlite-database-crud-operations-android\/\">SQLite access<\/a> and <a href=\"http:\/\/codetheory.in\/android-sharing-application-data-with-content-provider-and-content-resolver\/\">Content Providers<\/a>. Now access to a content provider will involve accessing some sort of persistent storage like a database or a file under the hood. Accessing a storage can be a long task and hence this should not be executed on the UI thread which will delay the rendering and could even lead to ANRs. Hence, background threads should be responsible for handling provider&#8217;s execution.<\/p>\n<p><!--more--><\/p>\n<p>Spawning new threads in the <code>ContentProvider<\/code> itself is not a good idea especially in the case of <code>query()<\/code> as you&#8217;ll then have to block and wait for the background thread to return the result (cursor) making it not asynchronous. Ideally execution must occur in a background thread and then the result communicated back to the UI thread. Now this could be implemented with Runnables, Threads and Handlers but Android provides us with a special class called <a href=\"http:\/\/developer.android.com\/reference\/android\/content\/AsyncQueryHandler.html\" target=\"_blank\" rel=\"noopener\"><code>AsyncQueryHandler<\/code><\/a> just for this purpose. This abstract class exposes an excellent interface to deal with the situation.<\/p>\n<p>Note: Ideally the background threads should be created by the application component that uses the provider by creating a <a href=\"http:\/\/developer.android.com\/reference\/android\/content\/ContentResolver.html\" target=\"_blank\" rel=\"noopener\"><code>ContentResolver<\/code><\/a> object. If the caller and provider are in the same application process, then the provider methods are invoked on the same thread as the <a href=\"http:\/\/developer.android.com\/reference\/android\/content\/ContentResolver.html\" target=\"_blank\" rel=\"noopener\"><code>ContentResolver<\/code><\/a> methods. However, if the processes are different then the provider implementation is invoked on binder threads (processes incoming IPCs).<\/p>\n<h2>Using AsyncQueryHandler<\/h2>\n<p><a href=\"http:\/\/developer.android.com\/reference\/android\/content\/AsyncQueryHandler.html\" target=\"_blank\" rel=\"noopener\"><code>AsyncQueryHandler<\/code><\/a> is basically an abstract class that wraps the <a href=\"http:\/\/developer.android.com\/reference\/android\/content\/ContentResolver.html\" target=\"_blank\" rel=\"noopener\"><code>ContentResolver<\/code><\/a> object and handles background execution of its operations (CRUD) as well as passing messages (result) from the between threads (background and main\/UI). It has four methods that wraps that of a <code>ContentResolver<\/code>:<\/p>\n<ul>\n<li>\n<a href=\"http:\/\/developer.android.com\/reference\/android\/content\/AsyncQueryHandler.html#startQuery(int, java.lang.Object, android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String)\" target=\"_blank\" rel=\"noopener\"><code>startQuery(int token, Object cookie, Uri uri, String[] projection, String selection, String[] selectionArgs, String orderBy)<\/code><\/a>\n<\/li>\n<li>\n<a href=\"http:\/\/developer.android.com\/reference\/android\/content\/AsyncQueryHandler.html#startInsert(int, java.lang.Object, android.net.Uri, android.content.ContentValues)\" target=\"_blank\" rel=\"noopener\"><code>startInsert(int token, Object cookie, Uri uri, ContentValues initialValues)<\/code><\/a>\n<\/li>\n<li>\n<a href=\"http:\/\/developer.android.com\/reference\/android\/content\/AsyncQueryHandler.html#startUpdate(int, java.lang.Object, android.net.Uri, android.content.ContentValues, java.lang.String, java.lang.String[])\" target=\"_blank\" rel=\"noopener\"><code>startUpdate(int token, Object cookie, Uri uri, ContentValues values, String selection, String[] selectionArgs)<\/code><\/a>\n<\/li>\n<li>\n<a href=\"http:\/\/developer.android.com\/reference\/android\/content\/AsyncQueryHandler.html#startDelete(int, java.lang.Object, android.net.Uri, java.lang.String, java.lang.String[]))\" target=\"_blank\" rel=\"noopener\"><code>startDelete(int token, Object cookie, Uri uri, String selection, String[] selectionArgs)<\/code><\/a>\n<\/li>\n<\/ul>\n<p>If you notice carefully, except the first two parameters, all others match their equivalent <code>ContentResolver<\/code> methods. Each of them, when called, execute the equivalent <code>ContentResolver<\/code> method on a background thread. When the provider is done with its operation, it sends the result back to <code>AsyncQueryHandler<\/code> that invokes the following callbacks that your implementation should override.<\/p>\n<pre class=\"brush: java; title: ; notranslate\" title=\"\">\r\nclass MyQueryHandler extends AsyncQueryHandler {\r\n\r\n    public MyQueryHandler(ContentResolver cr) {\r\n        super(cr);\r\n    }\r\n\r\n    @Override\r\n    protected void onQueryComplete(int token, Object cookie, Cursor cursor) {\r\n        \/\/ query() completed\r\n    }\r\n\r\n    @Override\r\n    protected void onInsertComplete(int token, Object cookie, Uri uri) {\r\n        \/\/ insert() completed\r\n    }\r\n\r\n    @Override\r\n    protected void onUpdateComplete(int token, Object cookie, int result) {\r\n        \/\/ update() completed\r\n    }\r\n\r\n    @Override\r\n    protected void onDeleteComplete(int token, Object cookie, int result) {\r\n        \/\/ delete() completed\r\n    }\r\n}\r\n<\/pre>\n<p>The last parameter for all the callbacks are results which has the same type as that of the return value of the underlying <code>ContentResolver<\/code> methods (<code>query()<\/code>, <code>insert()<\/code>, <code>update()<\/code>, <code>delete()<\/code>). Let&#8217;s discuss the first two methods of the calls and callbacks:<\/p>\n<ul>\n<li>\nToken: It&#8217;s a user-defined request code that identifies what kind of a request this is. This can be used with <a href=\"http:\/\/developer.android.com\/reference\/android\/content\/AsyncQueryHandler.html#cancelOperation(int)\" target=\"_blank\" rel=\"noopener\"><code>cancelOperation()<\/code><\/a> to cancel unprocessed requests submitted with that token.\n<\/li>\n<li>\nCookie: It&#8217;s a data container object that can be passed from the request to the response (callback) so that it can be used for some purpose like identifying the request if necessary.\n<\/li>\n<\/ul>\n<p><code>AsyncQueryHandler<\/code> is mostly created and executes provider operations on the UI thread, but it can be done on any other thread. The callbacks are <strong>always<\/strong> called on the thread that creates the <code>AsyncQueryHandler<\/code>.<\/p>\n<p>Let&#8217;s get in action with some code now. We&#8217;ll convert the <code>query()<\/code> code from our <a href=\"http:\/\/codetheory.in\/android-sharing-application-data-with-content-provider-and-content-resolver\/\">content provider<\/a> article to make use of <code>AsyncQueryHandler<\/code>:<\/p>\n<pre class=\"brush: java; title: ; notranslate\" title=\"\">\r\n\/\/ MainActivity.onCreate()\r\n\r\n\/\/ AsyncQueryHandler object\r\n\r\nAsyncQueryHandler queryHandler = new AsyncQueryHandler(getContentResolver()) {\r\n    @Override\r\n    protected void onQueryComplete(int token, Object cookie, Cursor cursor) {\r\n        int idIndex = cursor.getColumnIndex(UserDictionary.Words._ID);\r\n        int wordIndex = cursor.getColumnIndex(UserDictionary.Words.WORD);\r\n        int localeIndex = cursor.getColumnIndex(UserDictionary.Words.LOCALE);\r\n\r\n        if (cursor == null) {\r\n            \/\/ Some providers return null if an error occurs whereas others throw an exception\r\n        }\r\n        else if (cursor.getCount() &lt; 1) {\r\n            \/\/ No matches found\r\n        }\r\n        else {\r\n\r\n            while (cursor.moveToNext()) {\r\n                int id = cursor.getInt(idIndex);\r\n                String word = cursor.getString(wordIndex);\r\n                String locale = cursor.getString(localeIndex);\r\n\r\n                \/\/ Dumps &quot;ID: 1 Word: NewWord Locale: en_US&quot;\r\n                \/\/ I added this via Settings &gt; Language &amp; Input &gt; Personal Dictionary\r\n                Log.d(TAG, &quot;ID: &quot; + id + &quot; Word: &quot; + word + &quot; Locale: &quot; + locale);\r\n            }\r\n\r\n        }\r\n    }\r\n};\r\n\r\n\r\n\/\/ Construct query and execute\r\n\r\n\/\/ &quot;projection&quot; defines the columns that will be returned for each row\r\nString&#x5B;] projection = {\r\n        UserDictionary.Words._ID,       \/\/ Contract class constant for the _ID column\r\n        UserDictionary.Words.WORD,      \/\/ Contract class constant for the word column\r\n        UserDictionary.Words.LOCALE     \/\/ Contract class constant for the locale column\r\n};\r\n\r\n\/\/ Defines WHERE clause columns and placeholders\r\nString selectionClause = UserDictionary.Words._ID + &quot; = ?&quot;;\r\n\r\n\/\/ Define the WHERE clause's placeholder values\r\nString&#x5B;] selectionArgs = { &quot;1&quot; };\r\n\r\nqueryHandler.startQuery(\r\n        1, null,\r\n        UserDictionary.Words.CONTENT_URI,\r\n        projection,\r\n        selectionClause,\r\n        selectionArgs,\r\n        UserDictionary.Words.DEFAULT_SORT_ORDER \/\/ &quot;frequency DESC&quot;\r\n);\r\n<\/pre>\n<p>It&#8217;s all pretty straightforward. We create a <code>AsyncQueryHandler<\/code> object that implements the <code>onQueryComplete()<\/code> callback. On the object we execute <code>startQuery()<\/code> which is similar to <code>ContentResolver.query()<\/code> except the first two arguments which are token (<code>1<\/code>) and cookie (<code>null<\/code>). The entire query operation happens in the background and finally when the result set is ready, <code>onQueryComplete()<\/code> is called in the UI thread where you can use the <code>cursor<\/code> however you want to (display results or just log).<\/p>\n<p>Similarly you can also insert, update or delete records using relevant methods and callbacks.<\/p>\n<h2>Under the Hood<\/h2>\n<p>It&#8217;ll actually help us to understand how things work behidn the scenes with regards to <code>AsyncQueryHandler<\/code>. When one of these methods is called &#8211; <code>startQuery()<\/code>, <code>startInsert()<\/code>, <code>startUpdate()<\/code>, <code>startDelete()<\/code> &#8211; a <a href=\"http:\/\/developer.android.com\/reference\/android\/os\/Message.html\" target=\"_blank\" rel=\"noopener\"><code>Message<\/code><\/a> object is created that is populated with the <code>ContentResolver<\/code> arguments, <code>cookie<\/code> object data and the <code>token<\/code> which becomes the <code>what<\/code> field of the <a href=\"http:\/\/developer.android.com\/reference\/android\/os\/Message.html\" target=\"_blank\" rel=\"noopener\"><code>Message<\/code><\/a> (can be later used to <code>cancelOperation()<\/code>). This <a href=\"http:\/\/developer.android.com\/reference\/android\/os\/Message.html\" target=\"_blank\" rel=\"noopener\"><code>Message<\/code><\/a> object is added to the <a href=\"http:\/\/developer.android.com\/reference\/android\/os\/MessageQueue.html\" target=\"_blank\" rel=\"noopener\"><code>MessageQueue<\/code><\/a> of a single background thread. All <code>AsynQueryHandler<\/code> instances within an application adds these provider requests messages to this same queue on a single background thread. This is not really problematic as accessing providers (eventually data sources) are not very long tasks as a network operation.<\/p>\n<p>Once the background thread processes a request, the result is passed back in a <code>Message<\/code> object to the calling <code>AsyncQueryHandler<\/code> instance. Then the data is extracted and passed to the respective callbacks. This also means all the provider requests are handled sequentially.<\/p>\n<h2>Wrapping Up<\/h2>\n<p>In this article we discussed how <code>AsyncQueryHandler<\/code> can be used to so conveniently to execute our provider&#8217;s operations in a background thread without blocking the UI thread. In the <a href=\"http:\/\/codetheory.in\/asynchronous-background-execution-and-data-loading-with-loaders-framework-in-android\/\">next article<\/a> we&#8217;ll dive into another concept called <code>CursorLoader<\/code> that can be used for similar purpose.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>In our previous posts we discussed SQLite access and Content Providers. Now access to a content provider will involve accessing some sort of persistent storage like a database or a file under the hood. Accessing a storage can be a long task and hence this should not be executed on the UI thread which will &hellip; <a href=\"https:\/\/codetheory.in\/using-asyncqueryhandler-to-access-content-providers-asynchronously-in-android\/\" class=\"more-link\">Continue reading<span class=\"screen-reader-text\"> &#8220;Using AsyncQueryHandler to Access Content Providers Asynchronously in Android&#8221;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[121],"tags":[105,89],"_links":{"self":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts\/2006"}],"collection":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/comments?post=2006"}],"version-history":[{"count":5,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts\/2006\/revisions"}],"predecessor-version":[{"id":2068,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/posts\/2006\/revisions\/2068"}],"wp:attachment":[{"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/media?parent=2006"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/categories?post=2006"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/codetheory.in\/wp-json\/wp\/v2\/tags?post=2006"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}