Documentation and formatting

Author: mickael-menu

readium/lcp/src/main/java/org/readium/r2/lcp/LcpPublicationRetriever.kt

@@ -21,43 +21,143 @@ import org.readium.r2.shared.util.mediatype.MediaType
 import org.readium.r2.shared.util.mediatype.MediaTypeRetriever
 
 /**
- * Util to acquire a protected publication from standalone LCPL's bytes.
+ * Utility to acquire a protected publication from an LCP License Document.
  */
 public class LcpPublicationRetriever(
     context: Context,
     private val downloadManager: DownloadManager,
     private val mediaTypeRetriever: MediaTypeRetriever
 ) {
 
-    private val coroutineScope: CoroutineScope =
-        MainScope()
-
     @JvmInline
     public value class RequestId(public val value: String)
 
     public interface Listener {
 
+        /**
+         * Called when the publication has been successfully acquired.
+         */
         public fun onAcquisitionCompleted(
             requestId: RequestId,
             acquiredPublication: LcpService.AcquiredPublication
         )
 
+        /**
+         * The acquisition with ID [requestId] has downloaded [downloaded] out of [expected] bytes.
+         */
         public fun onAcquisitionProgressed(
             requestId: RequestId,
             downloaded: Long,
             expected: Long?
         )
 
+        /**
+         * The acquisition with ID [requestId] has failed with the given [error].
+         */
         public fun onAcquisitionFailed(
             requestId: RequestId,
             error: LcpException
         )
 
+        /**
+         * The acquisition with ID [requestId] has been cancelled.
+         */
         public fun onAcquisitionCancelled(
             requestId: RequestId
         )
     }
 
+    /**
+     * Submits a new request to acquire the publication protected with the given [license].
+     *
+     * The given [listener] will automatically be registered.
+     *
+     * Returns the ID of the acquisition request, which can be used to cancel it.
+     */
+    public fun retrieve(
+        license: LicenseDocument,
+        downloadTitle: String,
+        downloadDescription: String? = null,
+        listener: Listener
+    ): RequestId {
+        val requestId = fetchPublication(
+            license,
+            downloadTitle,
+            downloadDescription
+        )
+        register(requestId, listener)
+        return requestId
+    }
+
+    /**
+     * Registers a listener for the acquisition with the given [requestId].
+     *
+     * If the [downloadManager] provided during construction supports background downloading, this
+     * should typically be used when you get create a new instance after the app restarted.
+     */
+    public fun register(
+        requestId: RequestId,
+        listener: Listener
+    ) {
+        listeners.getOrPut(requestId) {
+            downloadManager.register(DownloadManager.RequestId(requestId.value), downloadListener)
+            mutableListOf()
+        }.add(listener)
+    }
+
+    /**
+     * Cancels the acquisition with the given [requestId].
+     */
+    public fun cancel(requestId: RequestId) {
+        downloadManager.cancel(DownloadManager.RequestId(requestId.value))
+        downloadsRepository.removeDownload(requestId.value)
+    }
+
+    /**
+     * Releases any in-memory resource associated with this [LcpPublicationRetriever].
+     *
+     * If the pending acquisitions cannot continue in the background, they will be cancelled.
+     */
+    public fun close() {
+        downloadManager.close()
+    }
+
+    private val coroutineScope: CoroutineScope =
+        MainScope()
+
+    private val formatRegistry: FormatRegistry =
+        FormatRegistry()
+
+    private val downloadsRepository: LcpDownloadsRepository =
+        LcpDownloadsRepository(context)
+
+    private val downloadListener: DownloadManager.Listener =
+        DownloadListener()
+
+    private val listeners: MutableMap<RequestId, MutableList<Listener>> =
+        mutableMapOf()
+
+    private fun fetchPublication(
+        license: LicenseDocument,
+        downloadTitle: String,
+        downloadDescription: String?
+    ): RequestId {
+        val url = Url(license.publicationLink.url)
+
+        val requestId = downloadManager.submit(
+            request = DownloadManager.Request(
+                url = url,
+                title = downloadTitle,
+                description = downloadDescription,
+                headers = emptyMap()
+            ),
+            listener = downloadListener
+        )
+
+        downloadsRepository.addDownload(requestId.value, license.json)
+        return RequestId(requestId.value)
+    }
+
     private inner class DownloadListener : DownloadManager.Listener {
 
         override fun onDownloadCompleted(
@@ -159,67 +259,4 @@ public class LcpPublicationRetriever(
             listeners.remove(lcpRequestId)
         }
     }
-
-    private val formatRegistry: FormatRegistry =
-        FormatRegistry()
-
-    private val downloadsRepository: LcpDownloadsRepository =
-        LcpDownloadsRepository(context)
-
-    private val downloadListener: DownloadManager.Listener =
-        DownloadListener()
-
-    private val listeners: MutableMap<RequestId, MutableList<Listener>> =
-        mutableMapOf()
-
-    public fun register(
-        requestId: RequestId,
-        listener: Listener
-    ) {
-        listeners.getOrPut(requestId) {
-            downloadManager.register(DownloadManager.RequestId(requestId.value), downloadListener)
-            mutableListOf()
-        }.add(listener)
-    }
-
-    public fun retrieve(
-        license: LicenseDocument,
-        downloadTitle: String,
-        downloadDescription: String? = null,
-        listener: Listener
-    ): RequestId {
-        val requestId = fetchPublication(
-            license,
-            downloadTitle,
-            downloadDescription
-        )
-        register(requestId, listener)
-        return requestId
-    }
-
-    public fun cancel(requestId: RequestId) {
-        downloadManager.cancel(DownloadManager.RequestId(requestId.value))
-        downloadsRepository.removeDownload(requestId.value)
-    }
-
-    private fun fetchPublication(
-        license: LicenseDocument,
-        downloadTitle: String,
-        downloadDescription: String?
-    ): RequestId {
-        val url = Url(license.publicationLink.url)
-
-        val requestId = downloadManager.submit(
-            request = DownloadManager.Request(
-                url = url,
-                title = downloadTitle,
-                description = downloadDescription,
-                headers = emptyMap()
-            ),
-            listener = downloadListener
-        )
-
-        downloadsRepository.addDownload(requestId.value, license.json)
-        return RequestId(requestId.value)
-    }
 }

readium/lcp/src/main/java/org/readium/r2/lcp/LcpService.kt

@@ -53,11 +53,7 @@ public interface LcpService {
      * Acquires a protected publication from a standalone LCPL's bytes.
      *
      * You can cancel the on-going acquisition by cancelling its parent coroutine context.
-     *    @Deprecated(
-     "Use a LcpPublicationRetriever instead.",
-     ReplaceWith("publicationRetriever()"),
-     level = DeprecationLevel.ERROR
-     )
+     *
      * @param onProgress Callback to follow the acquisition progress from 0.0 to 1.0.
      */
     @Deprecated(
@@ -125,9 +121,8 @@ public interface LcpService {
     ): Try<LcpLicense, LcpException>
 
     /**
-     * Creates a [LcpPublicationRetriever] instance which can be used to acquire a protected
-     * publication from standalone LCPL's bytes.
-     *
+     * Creates an [LcpPublicationRetriever] instance which can be used to acquire a protected
+     * publication from an LCP License Document.
      */
     public fun publicationRetriever(): LcpPublicationRetriever
 
@@ -215,8 +210,8 @@ public interface LcpService {
     }
 
     @Deprecated(
-        "Use `acquirePublication()` with coroutines instead",
-        ReplaceWith("acquirePublication(lcpl)"),
+        "Use a LcpPublicationRetriever instead.",
+        ReplaceWith("publicationRetriever()"),
         level = DeprecationLevel.ERROR
     )
     @DelicateCoroutinesApi

readium/shared/src/main/java/org/readium/r2/shared/util/MapCompanion.kt

@@ -9,6 +9,8 @@
 
 package org.readium.r2.shared.util
 
+import org.readium.r2.shared.InternalReadiumApi
+
 /**
  * Encapsulates a [Map] into a more limited query API.
  *
@@ -24,6 +26,7 @@ package org.readium.r2.shared.util
  * val layout: Layout? = Layout("reflowable")
  * ```
  */
+@InternalReadiumApi
 public open class MapCompanion<K, E>(protected val map: Map<K, E>) {
 
     public constructor(elements: Array<E>, keySelector: (E) -> K) :
@@ -60,6 +63,7 @@ public open class MapCompanion<K, E>(protected val map: Map<K, E>) {
 /**
  * Extends a [MapCompanion] by adding a [default] value as a fallback.
  */
+@InternalReadiumApi
 public open class MapWithDefaultCompanion<K, E>(map: Map<K, E>, public val default: E) : MapCompanion<K, E>(
     map
 ) {

readium/shared/src/main/java/org/readium/r2/shared/util/downloads/DownloadManager.kt

@@ -8,9 +8,17 @@ package org.readium.r2.shared.util.downloads
 
 import java.io.File
 import org.readium.r2.shared.util.Url
+import org.readium.r2.shared.util.downloads.android.AndroidDownloadManager
+import org.readium.r2.shared.util.downloads.foreground.ForegroundDownloadManager
 
 /**
- * Retrieves files through Http with various features depending on implementations.
+ * Manages a set of concurrent files downloaded through HTTP.
+ *
+ * Choose the implementation that best fits your needs:
+ * - [AndroidDownloadManager] for downloading files in the background with the Android system
+ * service, even if the app is stopped.
+ * - [ForegroundDownloadManager] for a simpler implementation based on HttpClient which cancels
+ * the on-going download when the app is closed.
  */
 public interface DownloadManager {
 
@@ -77,46 +85,52 @@ public interface DownloadManager {
     public interface Listener {
 
         /**
-         * Download with id [requestId] successfully completed and is available at [file].
+         * The download with ID [requestId] has been successfully completed and is now available at
+         * [file].
          */
         public fun onDownloadCompleted(requestId: RequestId, file: File)
 
         /**
-         * [downloaded] / [expected] bytes have been downloaded for request with id [requestId].
+         * The request with ID [requestId] has downloaded [downloaded] out of [expected] bytes.
          */
         public fun onDownloadProgressed(requestId: RequestId, downloaded: Long, expected: Long?)
 
         /**
-         * Download with id [requestId] failed with [error].
+         * The download with ID [requestId] failed due to [error].
          */
         public fun onDownloadFailed(requestId: RequestId, error: Error)
 
         /**
-         * Download with id [requestId] has been cancelled.
+         * The download with ID [requestId] has been cancelled.
          */
         public fun onDownloadCancelled(requestId: RequestId)
     }
 
     /**
-     * Submits a new request to this [DownloadManager]. [listener] will automatically be registered.
+     * Submits a new request to this [DownloadManager]. The given [listener] will automatically be
+     * registered.
+     *
+     * Returns the ID of the download request, which can be used to cancel it.
      */
     public fun submit(request: Request, listener: Listener): RequestId
 
     /**
-     * Registers a listener for the download with [requestId].
+     * Registers a listener for the download with the given [requestId].
      *
-     * If your [DownloadManager] supports background downloading, this should typically be used
-     * when you get back a new instance after the app restarted.
+     * If your [DownloadManager] supports background downloading, this should typically be used when
+     * you get create a new instance after the app restarted.
      */
     public fun register(requestId: RequestId, listener: Listener)
 
     /**
-     * Cancels the download with [requestId].
+     * Cancels the download with the given [requestId].
      */
     public fun cancel(requestId: RequestId)
 
     /**
      * Releases any in-memory resource associated with this [DownloadManager].
+     *
+     * If the pending downloads cannot continue in the background, they will be cancelled.
      */
     public fun close()
 }