Add option to disable GroupMembership validation checks in Insert and ProfileInsert APIs

[vestrel00]

Problem

As discussed in #317 (comment), there is room for speed optimization when inserting new RawContacts.

Currently, for each RawContact, the Insert and ProfileInsert APIs will perform several queries on Accounts and Groups to make sure that the memberships are valid (belonging to groups that actually exist for the particular chosen Account and that there are no duplicate memberships); https://github.com/vestrel00/contacts-android/blob/0.3.1/core/src/main/java/contacts/core/Insert.kt#L477

These internal queries could be slowing down the insert operation per new RawContact.

Solution

Add a function to the Insert and ProfileInsert APIs that will allow API users to disable these internal checks (enabled by default).

This should reduce insert speeds per RawContact a little bit. Combined with other optimization options in the discussion, this could help reduce the amount of time required to insert a large number of new RawContacts (a use case that may be useful for those implementing sync adapters).

• Disable the GroupMembership validation checks in the internal Insert operation performed in the MoveRawContactsAcrossAccounts API (because GroupMembership validation is already being performed prior to the internal insert operation); https://github.com/vestrel00/contacts-android/blob/0.3.1/core/src/main/java/contacts/core/accounts/MoveRawContactsAcrossAccounts.kt#L471
• Update Kotlin docs
• Update markdown docs (insert-contacts.md, insert-profile.md)
• Update gh-pages

Note

EDIT: I decided to create a separate ticket for the changes noted here to raise awareness for the next release. Here it is; #330

There is an extra optimization that we can perform even when the the internal check is enabled. Instead of querying the Groups of the Account for every RawContact,

ℹ️ The following is pseudocode.

for (rawContact in rawContacts) {
    val groupsList = getAccountGroupsList(rawContact.account)
    val validGroupMemberships  = getValidGroupMemberships(rawContact.groupMemberships, groupsList)
    ...
}

We may query Groups once per insert operation (on commit()) instead,

val accountGroupsMap = getAccountGroupsMap(rawContacts.map { it.account })
for (rawContact in rawContacts) {
    val validGroupMemberships  = getValidGroupMemberships(rawContact.groupMemberships, accountGroupsMap[rawContact.account])
    ...
}

Another note

A similar optimization can be done for Update APIs. However, cost to implement this is much higher for Update APIs because the code within GroupMembershipOperation.updateInsertOrDelete is much more complex than GroupMembershipOperation.insertForNewRawContact.

So, let's wait until someone in the community to raise an issue or discussion for it, if ever 😰

[vestrel00]

This is included in release 0.3.2.