Add LocatorCollection

r2-shared/src/main/java/org/readium/r2/shared/extensions/JSON.kt

@@ -76,6 +76,19 @@ fun JSONObject.putIfNotEmpty(name: String, jsonObject: JSONObject?) {
     put(name, jsonObject)
 }
 
+/**
+ * Maps [name] to [jsonArray], clobbering any existing name/value mapping with the same name. If
+ * the [JSONArray] is empty, any existing mapping for [name] is removed.
+ */
+fun JSONObject.putIfNotEmpty(name: String, jsonArray: JSONArray?) {
+    if (jsonArray == null || jsonArray.length() == 0) {
+        remove(name)
+        return
+    }
+
+    put(name, jsonArray)
+}
+
 /**
  * Maps [name] to [jsonable] after converting it to a [JSONObject], clobbering any existing
  * name/value mapping with the same name. If the [JSONObject] argument is empty, any existing mapping

r2-shared/src/main/java/org/readium/r2/shared/publication/Locator.kt

@@ -12,9 +12,11 @@ package org.readium.r2.shared.publication
 import android.os.Parcelable
 import kotlinx.parcelize.Parcelize
 import kotlinx.parcelize.WriteWith
+import org.json.JSONArray
 import org.json.JSONObject
 import org.readium.r2.shared.JSONable
 import org.readium.r2.shared.extensions.*
+import org.readium.r2.shared.toJSON
 import org.readium.r2.shared.util.logging.WarningLogger
 import org.readium.r2.shared.util.logging.log
 
@@ -96,7 +98,6 @@ data class Locator(
                     otherLocations = json?.toMap() ?: emptyMap()
                 )
             }
-
         }
 
         @Deprecated("Renamed to [fragments]", ReplaceWith("fragments"))
@@ -186,6 +187,12 @@ data class Locator(
             )
         }
 
+        fun fromJSONArray(
+            json: JSONArray?,
+            warnings: WarningLogger? = null
+        ): List<Locator> {
+            return json.parseObjects { Locator.fromJSON(it as? JSONObject, warnings) }
+        }
     }
 
 }
@@ -204,3 +211,72 @@ fun Link.toLocator(): Locator {
         )
     )
 }
+
+/**
+ * Represents a sequential list of `Locator` objects.
+ *
+ * For example, a search result or a list of positions.
+ */
+@Parcelize
+data class LocatorCollection(
+    val metadata: Metadata = Metadata(),
+    val links: List<Link> = emptyList(),
+    val locators: List<Locator> = emptyList(),
+) : JSONable, Parcelable {
+
+    /**
+     * Holds the metadata of a `LocatorCollection`.
+     *
+     * @param numberOfItems Indicates the total number of locators in the collection.
+     */
+    @Parcelize
+    data class Metadata(
+        val localizedTitle: LocalizedString? = null,
+        val numberOfItems: Int? = null,
+        val otherMetadata: @WriteWith<JSONParceler> Map<String, Any> = mapOf(),
+    ) : JSONable, Parcelable {
+
+        /**
+         * Returns the default translation string for the [localizedTitle].
+         */
+        val title: String? get() = localizedTitle?.string
+
+        override fun toJSON() = JSONObject(otherMetadata).apply {
+            putIfNotEmpty("title", localizedTitle)
+            putOpt("numberOfItems", numberOfItems)
+        }
+
+        companion object {
+
+            fun fromJSON(json: JSONObject?, warnings: WarningLogger? = null): Metadata {
+                json ?: return Metadata()
+
+                val localizedTitle = LocalizedString.fromJSON(json.remove("title"), warnings)
+                val numberOfItems = json.optPositiveInt("numberOfItems", remove = true)
+
+                return Metadata(
+                    localizedTitle = localizedTitle,
+                    numberOfItems = numberOfItems,
+                    otherMetadata = json.toMap()
+                )
+            }
+        }
+    }
+
+    override fun toJSON() = JSONObject().apply {
+        putIfNotEmpty("metadata", metadata.toJSON())
+        putIfNotEmpty("links", links.toJSON())
+        put("locators", locators.toJSON())
+    }
+
+    companion object {
+
+        fun fromJSON(json: JSONObject?, warnings: WarningLogger? = null): LocatorCollection {
+            return LocatorCollection(
+                metadata = Metadata.fromJSON(json?.optJSONObject("metadata"), warnings),
+                links = Link.fromJSONArray(json?.optJSONArray("links"), warnings = warnings),
+                locators = Locator.fromJSONArray(json?.optJSONArray("locators"), warnings),
+            )
+        }
+    }
+}

r2-shared/src/test/java/org/readium/r2/shared/publication/LocatorTest.kt

@@ -295,3 +295,213 @@ class LocatorTest {
     }
 
 }
+
+class LocatorCollectionTest {
+
+    @Test fun `parse {LocatorCollection} minimal JSON`() {
+        assertEquals(
+            LocatorCollection(),
+            LocatorCollection.fromJSON(JSONObject("{}"))
+        )
+    }
+
+    @Test fun `parse {LocatorCollection} full JSON`() {
+        assertEquals(
+            LocatorCollection(
+                metadata = LocatorCollection.Metadata(
+                    localizedTitle = LocalizedString.fromStrings(mapOf(
+                        "en" to "Searching <riddle> in Alice in Wonderlands - Page 1",
+                        "fr" to "Recherche <riddle> dans Alice in Wonderlands – Page 1"
+                    )),
+                    numberOfItems = 3,
+                    otherMetadata = mapOf(
+                        "extraMetadata" to "value"
+                    )
+                ),
+                links = listOf(
+                    Link(rels = setOf("self"), href = "/978-1503222687/search?query=apple", type = "application/vnd.readium.locators+json"),
+                    Link(rels = setOf("next"), href = "/978-1503222687/search?query=apple&page=2", type = "application/vnd.readium.locators+json"),
+                ),
+                locators = listOf(
+                    Locator(
+                        href = "/978-1503222687/chap7.html",
+                        type = "application/xhtml+xml",
+                        locations = Locator.Locations(
+                            fragments = listOf(":~:text=riddle,-yet%3F'"),
+                            progression = 0.43
+                        ),
+                        text = Locator.Text(
+                            before = "'Have you guessed the ",
+                            highlight = "riddle",
+                            after = " yet?' the Hatter said, turning to Alice again."
+                        )
+                    ),
+                    Locator(
+                        href = "/978-1503222687/chap7.html",
+                        type = "application/xhtml+xml",
+                        locations = Locator.Locations(
+                            fragments = listOf(":~:text=in%20asking-,riddles"),
+                            progression = 0.47
+                        ),
+                        text = Locator.Text(
+                            before = "I'm glad they've begun asking ",
+                            highlight = "riddles",
+                            after = ".--I believe I can guess that,"
+                        )
+                    )
+                )
+            ),
+            LocatorCollection.fromJSON(JSONObject("""{
+              "metadata": {
+                "title": {
+                    "en": "Searching <riddle> in Alice in Wonderlands - Page 1",
+                    "fr": "Recherche <riddle> dans Alice in Wonderlands – Page 1"
+                },
+                "numberOfItems": 3,
+                "extraMetadata": "value"
+              },
+              "links": [
+                {"rel": "self", "href": "/978-1503222687/search?query=apple", "type": "application/vnd.readium.locators+json"},
+                {"rel": "next", "href": "/978-1503222687/search?query=apple&page=2", "type": "application/vnd.readium.locators+json"}
+              ],
+              "locators": [
+                {
+                  "href": "/978-1503222687/chap7.html",
+                  "type": "application/xhtml+xml",
+                  "locations": {
+                    "fragments": [
+                      ":~:text=riddle,-yet%3F'"
+                    ],
+                    "progression": 0.43
+                  },
+                  "text": {
+                    "before": "'Have you guessed the ",
+                    "highlight": "riddle",
+                    "after": " yet?' the Hatter said, turning to Alice again."
+                  }
+                },
+                {
+                  "href": "/978-1503222687/chap7.html",
+                  "type": "application/xhtml+xml",
+                  "locations": {
+                    "fragments": [
+                      ":~:text=in%20asking-,riddles"
+                    ],
+                    "progression": 0.47
+                  },
+                  "text": {
+                    "before": "I'm glad they've begun asking ",
+                    "highlight": "riddles",
+                    "after": ".--I believe I can guess that,"
+                  }
+                }
+              ]
+            }"""))
+        )
+    }
+
+    @Test fun `get {Locator} minimal JSON`() {
+        assertJSONEquals(
+            JSONObject("""{
+                "locators": []
+            }"""),
+            LocatorCollection().toJSON()
+        )
+    }
+
+    @Test fun `get {Locator} full JSON`() {
+        assertJSONEquals(
+            JSONObject("""{
+              "metadata": {
+                "title": {
+                    "en": "Searching <riddle> in Alice in Wonderlands - Page 1",
+                    "fr": "Recherche <riddle> dans Alice in Wonderlands – Page 1"
+                },
+                "numberOfItems": 3,
+                "extraMetadata": "value"
+              },
+              "links": [
+                {"rel": ["self"], "href": "/978-1503222687/search?query=apple", "type": "application/vnd.readium.locators+json", "templated": false},
+                {"rel": ["next"], "href": "/978-1503222687/search?query=apple&page=2", "type": "application/vnd.readium.locators+json", "templated": false}
+              ],
+              "locators": [
+                {
+                  "href": "/978-1503222687/chap7.html",
+                  "type": "application/xhtml+xml",
+                  "locations": {
+                    "fragments": [
+                      ":~:text=riddle,-yet%3F'"
+                    ],
+                    "progression": 0.43
+                  },
+                  "text": {
+                    "before": "'Have you guessed the ",
+                    "highlight": "riddle",
+                    "after": " yet?' the Hatter said, turning to Alice again."
+                  }
+                },
+                {
+                  "href": "/978-1503222687/chap7.html",
+                  "type": "application/xhtml+xml",
+                  "locations": {
+                    "fragments": [
+                      ":~:text=in%20asking-,riddles"
+                    ],
+                    "progression": 0.47
+                  },
+                  "text": {
+                    "before": "I'm glad they've begun asking ",
+                    "highlight": "riddles",
+                    "after": ".--I believe I can guess that,"
+                  }
+                }
+              ]
+            }"""),
+            LocatorCollection(
+                metadata = LocatorCollection.Metadata(
+                    localizedTitle = LocalizedString.fromStrings(mapOf(
+                        "en" to "Searching <riddle> in Alice in Wonderlands - Page 1",
+                        "fr" to "Recherche <riddle> dans Alice in Wonderlands – Page 1"
+                    )),
+                    numberOfItems = 3,
+                    otherMetadata = mapOf(
+                        "extraMetadata" to "value"
+                    )
+                ),
+                links = listOf(
+                    Link(rels = setOf("self"), href = "/978-1503222687/search?query=apple", type = "application/vnd.readium.locators+json"),
+                    Link(rels = setOf("next"), href = "/978-1503222687/search?query=apple&page=2", type = "application/vnd.readium.locators+json"),
+                ),
+                locators = listOf(
+                    Locator(
+                        href = "/978-1503222687/chap7.html",
+                        type = "application/xhtml+xml",
+                        locations = Locator.Locations(
+                            fragments = listOf(":~:text=riddle,-yet%3F'"),
+                            progression = 0.43
+                        ),
+                        text = Locator.Text(
+                            before = "'Have you guessed the ",
+                            highlight = "riddle",
+                            after = " yet?' the Hatter said, turning to Alice again."
+                        )
+                    ),
+                    Locator(
+                        href = "/978-1503222687/chap7.html",
+                        type = "application/xhtml+xml",
+                        locations = Locator.Locations(
+                            fragments = listOf(":~:text=in%20asking-,riddles"),
+                            progression = 0.47
+                        ),
+                        text = Locator.Text(
+                            before = "I'm glad they've begun asking ",
+                            highlight = "riddles",
+                            after = ".--I believe I can guess that,"
+                        )
+                    )
+                )
+            ).toJSON()
+        )
+    }
+
+}