1. query(uri, projection, selection = "column=" + value, selectionArgs = null, sortOrder)
2. query(uri, projection, selection = "column=?", selectionArgs = { value_as_string }, sortOrder)

Obviously, the first one is more straightforward and convenient. Then what’s good about the second one?

Let me try to sell the goodness of selectionArgs via a simple example.

Suppose you are querying contacts with phone number, say, “+8612345678901″. With the first style, you get the WHERE clause "number=+8612345678901" which is the result of string concatenation ‘"number=" + "+8612345678901"‘.

It is easy to see that phone numbers are not pure numbers, i.e., they are not numeric. For example, the number “(010) 87654321 ” and “010-87654321-001″, are valid phone numbers, but are neither valid integer nor real numbers¹. Thus, the the type of the number column (storage class in SQLite’s idiom) is TEXT.

From this nonnumeric phone number string raises a problem, a quite subtle one. With its dynamic type system、column affinity and type conversion, SQLite will try to convert “+8612345678901″ to a text string. But the express “+8612345678901″ is numeric originally, because it has no quote marks surrounding it, and numeric values are operated according numeric rules first. So it is first normalized to “8612345678901″, and then the normalized value is converted to a text string “‘8612345678901‘“.

So the query that is really fed into the SQLite engine is something like this:

But as a text string, ’8612345678901′ can not be matched with ‘+8612345678901′, and the query fails.

We were suffering this kind of adversity until selectionArgs came to save the day.

With the second style, Android SQL query builder will replace ?s in selection with the values from selectionArgs, in order that they appear in the selection. The values must be String and will be treated as text strings by SQLite, i.e., they must be converted to their String representation first if they are not String, and will be quoted automatically when replacing the ?s. So the query that is fed into the SQLite engine is something like this:

At this point, it doesn’t matter whether the underlying column type is really TEXT or not, because whatever the TEXT value is derived from, it can be correctly cast back to the original column type. The key point is that TEXT can be losslessly converted to any other types, but not necessarily vice versa as shown above.

In fact, we can stick to the first style by manually simulating the works done by Android SQL query builder this way:

But as you can see, it is such a tedious concatenation with just one query column, you don’t want to imagine the mess with more complex queries, do you?

Actually, I’m doomed to fail, because it is just Mission Impossible.

For the time being, a BroadcastReceiver for "android.intent.action.PHONE_STATE" is the only chance for application developers to generally probe for incoming calls. However, it comes too late.

Here is why.

com.android.internal.telephony.gsm.RIL.RILReceiver.run():                                               +---+ 
                                       android.net.LocalSocket.getInputStream() <-----------------------|   |
                                                                  /                                     |   |
                                                                 |                                      |   |
                                                                 v                                      | R |
  com.android.internal.telephony.gsm.RIL.readRilMessage(InputStream, byte[])                            | A |
  com.android.internal.telephony.gsm.RIL.processResponse(Parcel):                                       | D |
  Case 1: Unsolicited Commands - Incoming Call                                                          | I |
    com.android.internal.telephony.gsm.RIL.processUnsolicited(Parcel)                                   | O |
    com.android.internal.telephony.BaseCommands.mCallStateRegistrants.notifyRegistrants(AsyncResult)    |   |
    com.android.internal.telephony.gsm.CallTracker.sendMessage(Message)                                 |   |
                                                        |                                               |   |
                                                        |                                               | S |
                                                        v                                               | Y |
    com.android.internal.telephony.gsm.CallTracker.handleMessage(Message)                               | S |
    com.android.internal.telephony.gsm.CallTracker.pollCallsWhenSafe()                                  | T |
    com.android.internal.telephony.gsm.RIL.getCurrentCalls(Message)                                     | E |
    com.android.internal.telephony.gsm.RIL.send(RILRequest)                                             | M |
                                                     |                                                  |   |
                                                     |                                                  |   |
                                                     v                                                  |   |
    com.android.internal.telephony.gsm.RIL.RILSender.handleMessage(Message)                             |   |
                               android.net.LocalSocket.getOutputStream().write(byte[]) ---------------->|   |
                                                                                                        +---+    
  Case 2: Solicited Commands - Request Call Info
    com.android.internal.telephony.gsm.RIL.processSolicited(Parcel)
    com.android.internal.telephony.gsm.RIL.findAndRemoveRequestFromList(int)
    com.android.internal.telephony.gsm.RILRequest.mResult.sendToTarget()
                                                           |
                                                           |
                                                           v
    com.android.internal.telephony.gsm.CallTracker.handleMessage(Message)
    com.android.internal.telephony.gsm.CallTracker.handlePollCalls(AsyncResult)
    com.android.internal.telephony.gsm.GSMPhone.notifyNewRingingConnection(Connection)
    com.android.internal.telephony.PhoneBase.notifyNewRingingConnectionP(Connection):
      com.android.phone.CallNotifier.sendMessage(Message)
                                           |
                                           |
                                           v
      com.android.phone.CallNotifier.handleMessage(Message)
      com.android.phone.CallNotifier.onNewRingingConnection(AsyncResult)
      com.android.phone.PhoneUtils.showIncomingCallUi() <---------------- Users see incoming call
 
    com.android.internal.telephony.gsm.CallTracker.updatePhoneState()
    com.android.internal.telephony.gsm.GSMPhone.notifyPhoneStateChanged()
    com.android.internal.telephony.DefaultPhoneNotifier.notifyPhoneState(Phone)
    com.android.server.TelephonyRegistry.notifyCallState(int, String)
    com.android.server.TelephonyRegistry.broadcastCallStateChanged(int, String) <--- Too late to interfere

I put by the itch to untangle the knot until recently I set out to implement an OrderedMergeCursor¹, which should be a subclass of MergeCursor that merge-sorts pre-ordered cursors.

It turns out that the chain is quite long, and kinda entangled by the two content data concepts of Cursor: Content(ContentObservable->ContentObserver) and DataSet(DataSetObservable->DataSetObserver).

As I see it, Cursor’s Content is the source Cursor retrieves data from, while Cursor’s DataSet is the data Cursor has retrieved. It will be more clear in the notification chain below.

For simplicity, I will omit the enclosed ContentObservable/DataSetObservable of Cursor and Adapter, since they are just one more indirect layer without any real functionalities. You can think of Cursor and Adapter as Observable themselves.

Without further ado, here comes the untangled register chain and the opposite notification chain.

• Register Chain:
  

  ListView.setAdapter(CursorAdapter): Adapter.registerDataSetObserver(AdapterView.AdapterDataSetObserver) ^ ^ CursorAdapter <- CursorAdapter(Context, Cursor): Cursor.registerContentObserver(CursorAdapter.ChangeObserver) Cursor.registerDataSetObserver(CursorAdapter.MyDataSetObserver) ^ ^ Cursor <- ContentResolver.query(Uri, String[], String, String[], String): ContentProvider.query(Uri, String[], String, String[], String): AbstractCursor.setNotificationUri(ContentResolver, Uri): ContentResolver.registerContentObserver(Uri, boolean, AbstractCursor.SelfContentObserver)

• Notification Chain:
  

  ContentResolver.notifyChange(Uri, ContentObserver) ---> AbstractCursor.SelfContentObserver.onChange(boolean) ---> AbstractCursor.onChange(boolean) ---> CursorAdapter.ChangeObserver.onChange(boolean) ---> AbstractCursor.requery() ---> CursorAdapter.MyDataSetObserver.onChanged() ---> BaseAdapter.notifyDataSetChanged() ---> AdapterView.AdapterDataSetObserver.onChanged() ---> View.requestLayout()