Implemented Collection.delete(DocumentModel)

Author: snej

common/main/kotlin/com/couchbase/lite/CollectionExtensions.kt

@@ -52,13 +52,12 @@ fun <T: DocumentModel> Collection.getDocumentAs(id: String, deserializer: Deseri
     modelFromC4Doc(this, id, getC4Document(id), deserializer)
 
 
-/**
- * Saves a [DocumentModel] instance as a document in the collection, with a specified conflict handler.
- * If the model's [DocumentModel.documentMeta] property is null, it will be saved as a new document with the
- * given [docID], which must not be null.
- * Otherwise the [DocumentModel.documentMeta] property determines the document ID and prior revision ID, and the
- * [docID] parameter should be null.
- * After a successful save, the [DocumentModel.documentMeta] property is updated to the current state. */
+/** Saves a [DocumentModel] instance as a document in the collection, with a specified conflict handler.
+ *  If the model's [DocumentModel.documentMeta] property is null, it will be saved as a new document with the
+ *  given [docID], which must not be null.
+ *  Otherwise the [DocumentModel.documentMeta] property determines the document ID and prior revision ID, and the
+ *  [docID] parameter should be null.
+ *  After a successful save, the [DocumentModel.documentMeta] property is updated to the current state. */
 @ExperimentalSerializationApi
 inline fun <reified T: DocumentModel> Collection.save(model: T,
                                                       docID: String? = null,
@@ -80,7 +79,7 @@ fun <T: DocumentModel> Collection.save(model: T,
         doc = MutableDocument(docID)
     } else {
         require(meta.collection == this || meta.collection == null) {"saving document to wrong collection"}
-        require(docID == null || docID == meta.id) {"docID parameter does not match meta.id"}
+        require(docID == null || docID == meta.id) {"docID parameter does not match documentMeta.id"}
         doc = getDocument(meta.id)?.toMutable() ?: MutableDocument(meta.id)
     }
 
@@ -131,6 +130,31 @@ fun <T: DocumentModel> Collection.save(model: T,
 typealias ModelConflictHandler<T> = (T, T?)-> Boolean
 
 
+/** Deletes a model's document from the collection.
+ *  @throws CouchbaseLiteException if the [DocumentModel.documentMeta] property is null. */
+fun Collection.delete(model: DocumentModel, concurrencyControl: ConcurrencyControl = ConcurrencyControl.LAST_WRITE_WINS): Boolean {
+    val meta = model.documentMeta ?: throw CouchbaseLiteException("DocumentModel has no document ID")
+    require(meta.collection == this || meta.collection == null) {"deleting document from wrong collection"}
+    val doc = getDocument(meta.id) ?: return true
+    if (doc.revisionID != meta.revisionID && concurrencyControl == ConcurrencyControl.FAIL_ON_CONFLICT)
+        return false
+    if (!delete(doc, concurrencyControl))
+        return false
+    model.documentMeta = null
+    return true
+}
+
+
+/** Purges a model's document from the collection.
+ *  @throws CouchbaseLiteException if the [DocumentModel.documentMeta] property is null,
+ *                                 or the document doesn't exist in the collection. */
+fun Collection.purge(model: DocumentModel) {
+    val id = model.documentMeta?.id ?: throw CouchbaseLiteException("DocumentModel has no document ID")
+    purge(id)
+    model.documentMeta = null
+}
+
+
 /** Creates a [DocumentModel] instance from a [C4Document]. */
 private fun <T:DocumentModel> modelFromC4Doc(collection: Collection,
                                              docID: String,

common/main/kotlin/com/couchbase/lite/QueryExtensions.kt

@@ -23,22 +23,22 @@ import kotlinx.serialization.descriptors.StructureKind
 import kotlinx.serialization.serializer
 
 
-/** Uses Kotlin Serialization to create an object of type [T] from the query row.
- *  If the [key] parameter is non-null, it uses the row's value for that key as the source,
- *  instead of the entire row.
+/** Uses Kotlin Serialization to create an object of type [T] from a query result.
+ *  If the [key] parameter is non-null, it uses the result's value for that key as the source,
+ *  instead of the entire result.
  *
  *  For example, if your query is `SELECT name, age, shoeSize FROM people` and you have a
- *  serializable Person class with properties name, age and shoeSize, you can call:
+ *  serializable `Person` class with properties `name`, `age` and `shoeSize`, you can call:
  *  `val person = result.data<Person>()`
  *
- *  Or you could use the query `SELECT * as person FROM people` and create the Person with
+ *  Or you could use the query `SELECT * as person FROM people` and create the `Person` with
  *  `val person = result.data<Person>("person")`.
  *  */
 @ExperimentalSerializationApi
 inline fun <reified T> Result.data(key: String? = null): T =
     data(serializer(), key)
 
-/** Uses Kotlin Serialization to create a [DocumentModel] instance of type [T] from the query row.
+/** Uses Kotlin Serialization to create a [DocumentModel] instance of type [T] from the query result.
  *  This is a specialization of the one-parameter [data] method that adds a [metaKey] parameter.
  *
  *  The [metaKey] parameter is the name of the result property whose value comes from the N1QL
@@ -80,7 +80,7 @@ fun <T> Result.data(deserializer: DeserializationStrategy<T>,
     } else {
         // Deserializing a single value from the result:
         val i = getIndexForKey(key)
-        if (i < 0) throw CouchbaseLiteError("Query row has no property '$key'")
+        if (i < 0) throw CouchbaseLiteError("Query result has no property '$key'")
         deserializeFromFleece(columns[i], deserializer)
     }
     if (result is DocumentModel && metaKey != null)
@@ -119,7 +119,7 @@ private class Entry(override val key: String, override val value: FLValue) : Map
 // Creates a [DocumentMeta] from the "meta" column of a Result. (Note: It can't set the `collection`.)
 private fun Result.getDocumentMeta(key: String): DocumentMeta? {
     val i = getIndexForKey(key)
-    if (i < 0) throw CouchbaseLiteError("Query row has no property '$key'")
+    if (i < 0) throw CouchbaseLiteError("Query result has no property '$key'")
     val col = flValues[i]
     if (col.type != FLValue.DICT) return null
     val meta = col.asFLDict()

common/test/java/com/couchbase/lite/CollectionTest.kt

@@ -1217,7 +1217,7 @@ class CollectionTest : BaseDbTest() {
     }
 
     //---------------------------------------------
-    //  Model-based API
+    //  Model-based (serialization) API
     //---------------------------------------------
 
     @Test
@@ -1249,6 +1249,10 @@ class CollectionTest : BaseDbTest() {
         Assert.assertEquals(2, faves.count())
         Assert.assertEquals("XTC", faves.getString(0))
         Assert.assertEquals("Elvis Costello", faves.getString(1))
+
+        // Delete the model. `model` is out of date, so it will fail, but `gotModel` is OK:
+        Assert.assertFalse(testCollection.delete(model, ConcurrencyControl.FAIL_ON_CONFLICT))
+        Assert.assertTrue(testCollection.delete(gotModel, ConcurrencyControl.FAIL_ON_CONFLICT))
     }
 }