From 79e273b1ca1a5569ca8e1f4651078248327e7e45 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Wed, 27 Mar 2019 18:03:36 +0100
Subject: [PATCH] Add Doc

---
 .../database/helper/ChunkEntityHelper.kt      |  8 +--
 .../database/helper/RoomEntityHelper.kt       |  6 +-
 .../internal/extensions/RealmExtensions.kt    | 25 +++++++
 .../room/timeline/TokenChunkEventPersistor.kt | 69 ++++++++++++++++++-
 4 files changed, 96 insertions(+), 12 deletions(-)
 create mode 100644 matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/extensions/RealmExtensions.kt

diff --git a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/ChunkEntityHelper.kt b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/ChunkEntityHelper.kt
index 03dc9439..5579d737 100644
--- a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/ChunkEntityHelper.kt
+++ b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/ChunkEntityHelper.kt
@@ -25,6 +25,7 @@ import im.vector.matrix.android.internal.database.model.ChunkEntity
 import im.vector.matrix.android.internal.database.model.EventEntity
 import im.vector.matrix.android.internal.database.model.EventEntityFields
 import im.vector.matrix.android.internal.database.query.fastContains
+import im.vector.matrix.android.internal.extensions.assertIsManaged
 import im.vector.matrix.android.internal.session.room.timeline.PaginationDirection
 import io.realm.Sort
 
@@ -69,6 +70,7 @@ internal fun ChunkEntity.addAll(roomId: String,
                                 events: List<Event>,
                                 direction: PaginationDirection,
                                 stateIndexOffset: Int = 0,
+                                // Set to true for Event retrieved from a Permalink (i.e. not linked to live Chunk)
                                 isUnlinked: Boolean = false) {
     assertIsManaged()
     events.forEach { event ->
@@ -105,12 +107,6 @@ internal fun ChunkEntity.add(roomId: String,
     events.add(position, eventEntity)
 }
 
-private fun ChunkEntity.assertIsManaged() {
-    if (!isManaged) {
-        throw IllegalStateException("Chunk entity should be managed to use this function")
-    }
-}
-
 internal fun ChunkEntity.lastStateIndex(direction: PaginationDirection, defaultValue: Int = 0): Int {
     return when (direction) {
                PaginationDirection.FORWARDS  -> events.where().sort(EventEntityFields.STATE_INDEX, Sort.DESCENDING).findFirst()?.stateIndex
diff --git a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/RoomEntityHelper.kt b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/RoomEntityHelper.kt
index cec664c2..fb044315 100644
--- a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/RoomEntityHelper.kt
+++ b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/database/helper/RoomEntityHelper.kt
@@ -22,6 +22,7 @@ import im.vector.matrix.android.internal.database.mapper.updateWith
 import im.vector.matrix.android.internal.database.model.ChunkEntity
 import im.vector.matrix.android.internal.database.model.RoomEntity
 import im.vector.matrix.android.internal.database.query.fastContains
+import im.vector.matrix.android.internal.extensions.assertIsManaged
 
 
 internal fun RoomEntity.deleteOnCascade(chunkEntity: ChunkEntity) {
@@ -40,9 +41,8 @@ internal fun RoomEntity.addStateEvents(stateEvents: List<Event>,
                                        stateIndex: Int = Int.MIN_VALUE,
                                        filterDuplicates: Boolean = false,
                                        isUnlinked: Boolean = false) {
-    if (!isManaged) {
-        throw IllegalStateException("Chunk entity should be managed to use fast contains")
-    }
+    assertIsManaged()
+
     stateEvents.forEach { event ->
         if (event.eventId == null || (filterDuplicates && fastContains(event.eventId))) {
             return@forEach
diff --git a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/extensions/RealmExtensions.kt b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/extensions/RealmExtensions.kt
new file mode 100644
index 00000000..48945382
--- /dev/null
+++ b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/extensions/RealmExtensions.kt
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2019 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package im.vector.matrix.android.internal.extensions
+
+import io.realm.RealmObject
+
+internal fun RealmObject.assertIsManaged() {
+    if (!isManaged) {
+        throw IllegalStateException("${javaClass.simpleName} entity should be managed to use this function")
+    }
+}
\ No newline at end of file
diff --git a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/session/room/timeline/TokenChunkEventPersistor.kt b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/session/room/timeline/TokenChunkEventPersistor.kt
index 9289ee11..4234b24d 100644
--- a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/session/room/timeline/TokenChunkEventPersistor.kt
+++ b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/session/room/timeline/TokenChunkEventPersistor.kt
@@ -27,9 +27,73 @@ import im.vector.matrix.android.internal.database.query.findAllIncludingEvents
 import im.vector.matrix.android.internal.database.query.where
 import im.vector.matrix.android.internal.util.tryTransactionSync
 
-
+/**
+ * Insert Chunk in DB, and eventually merge with existing chunk event
+ */
 internal class TokenChunkEventPersistor(private val monarchy: Monarchy) {
 
+    /**
+     * <pre>
+     * ========================================================================================================
+     * | Backward case                                                                                        |
+     * ========================================================================================================
+     *
+     *                               *--------------------------*        *--------------------------*
+     *                               | startToken1              |        | startToken1              |
+     *                               *--------------------------*        *--------------------------*
+     *                               |                          |        |                          |
+     *                               |                          |        |                          |
+     *                               |  receivedChunk backward  |        |                          |
+     *                               |         Events           |        |                          |
+     *                               |                          |        |                          |
+     *                               |                          |        |                          |
+     *                               |                          |        |                          |
+     * *--------------------------*  *--------------------------*        |                          |
+     * | startToken0              |  | endToken1                |   =>   |       Merged chunk       |
+     * *--------------------------*  *--------------------------*        |          Events          |
+     * |                          |                                      |                          |
+     * |                          |                                      |                          |
+     * |      Current Chunk       |                                      |                          |
+     * |         Events           |                                      |                          |
+     * |                          |                                      |                          |
+     * |                          |                                      |                          |
+     * |                          |                                      |                          |
+     * *--------------------------*                                      *--------------------------*
+     * | endToken0                |                                      | endToken0                |
+     * *--------------------------*                                      *--------------------------*
+     *
+     *
+     * ========================================================================================================
+     * | Forward case                                                                                         |
+     * ========================================================================================================
+     *
+     * *--------------------------*                                      *--------------------------*
+     * | startToken0              |                                      | startToken0              |
+     * *--------------------------*                                      *--------------------------*
+     * |                          |                                      |                          |
+     * |                          |                                      |                          |
+     * |      Current Chunk       |                                      |                          |
+     * |         Events           |                                      |                          |
+     * |                          |                                      |                          |
+     * |                          |                                      |                          |
+     * |                          |                                      |                          |
+     * *--------------------------*  *--------------------------*        |                          |
+     * | endToken0                |  | startToken1              |   =>   |       Merged chunk       |
+     * *--------------------------*  *--------------------------*        |          Events          |
+     *                               |                          |        |                          |
+     *                               |                          |        |                          |
+     *                               |  receivedChunk forward   |        |                          |
+     *                               |         Events           |        |                          |
+     *                               |                          |        |                          |
+     *                               |                          |        |                          |
+     *                               |                          |        |                          |
+     *                               *--------------------------*        *--------------------------*
+     *                               | endToken1                |        | endToken1                |
+     *                               *--------------------------*        *--------------------------*
+     *
+     * ========================================================================================================
+     * </pre>
+     */
     fun insertInDb(receivedChunk: TokenChunkEvent,
                    roomId: String,
                    direction: PaginationDirection): Try<Boolean> {
@@ -60,11 +124,10 @@ internal class TokenChunkEventPersistor(private val monarchy: Monarchy) {
 
                     var currentChunk = if (direction == PaginationDirection.FORWARDS) {
                         prevChunk?.apply { this.nextToken = nextToken }
-                                ?: ChunkEntity.create(realm, prevToken, nextToken)
                     } else {
                         nextChunk?.apply { this.prevToken = prevToken }
-                                ?: ChunkEntity.create(realm, prevToken, nextToken)
                     }
+                            ?: ChunkEntity.create(realm, prevToken, nextToken)
 
                     currentChunk.addAll(roomId, receivedChunk.events, direction, isUnlinked = currentChunk.isUnlinked())