Documentation update

SRGSSR · Dec 17, 2024 · ad28c12 · ad28c12
1 parent 4511809
commit ad28c12
Show file tree

Hide file tree

Showing 6 changed files with 68 additions and 47 deletions.
diff --git a/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/SRGMediaItem.kt b/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/SRGMediaItem.kt
@@ -29,7 +29,7 @@ import ch.srgssr.pillarbox.player.source.PillarboxMediaSource
  *
  * ```kotlin
  * val mediaItem: MediaItem = SRGMediaItem("urn:rts:audio:3262363") {
- *     host(IlUrl.Default)
+ *     host(IlHost.PROD)
  *     vector(Vector.TV)
  * }
  * ```
@@ -61,7 +61,7 @@ fun SRGMediaItem(urn: String, block: SRGMediaItemBuilder.() -> Unit = {}): Media
  * **Usage example**
  * ```kotlin
  * val mediaItem: MediaItem = sourceItem.buildUpon {
- *     host(IlUrl.Stage)
+ *     host(IlHost.STAGE)
  * }
  * ```
  *
@@ -123,9 +123,9 @@ class SRGMediaItemBuilder internal constructor(mediaItem: MediaItem) {
     }
 
     /**
-     * Sets the host URL to the integration layer.
+     * Sets the host base URL to the integration layer.
      *
-     * @param host The URL of the integration layer server.
+     * @param host The base URL of the integration layer server.
      */
     fun host(host: IlHost) {
         this.host = host
@@ -168,9 +168,9 @@ class SRGMediaItemBuilder internal constructor(mediaItem: MediaItem) {
      */
     fun build(): MediaItem {
         val ilUrl = IlUrl(host = host, urn = urn, vector = vector, forceSAM = forceSAM, ilLocation = ilLocation)
-        mediaItemBuilder.setUri(ilUrl.uri)
-        mediaItemBuilder.setMediaId(ilUrl.urn)
-        mediaItemBuilder.setMimeType(MimeTypeSrg)
-        return mediaItemBuilder.build()
+        return mediaItemBuilder.setUri(ilUrl.uri)
+            .setMediaId(ilUrl.urn)
+            .setMimeType(MimeTypeSrg)
+            .build()
     }
 }
diff --git a/...siness/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlHost.kt b/...siness/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlHost.kt
@@ -5,8 +5,9 @@
 package ch.srgssr.pillarbox.core.business.integrationlayer.service
 
 /**
- * Object containing the different host URLs for the integration layer service.
- * @property baseHostUrl The base hostname url.
+ * Represents the different host URLs for the integration layer service.
+ *
+ * @property baseHostUrl The base URL of the environment.
  */
 enum class IlHost(val baseHostUrl: String) {
 
@@ -33,8 +34,9 @@ enum class IlHost(val baseHostUrl: String) {
         /**
          * Parses the given [url] and returns the corresponding [IlHost].
          *
-         * @param url The url to parse
-         * @return null if the [url] does not match any [IlHost].
+         * @param url The URL to parse.
+         *
+         * @return The matching [IlHost] or `null` if none was found.
          */
         fun parse(url: String): IlHost? {
             return entries.find { url.contains(it.baseHostUrl) }

diff --git a/...usiness/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlUrl.kt b/...usiness/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlUrl.kt
@@ -8,11 +8,11 @@ import android.net.Uri
 import ch.srgssr.pillarbox.core.business.integrationlayer.data.isValidMediaUrn
 
 /**
- * @property host the [IlHost] to use.
- * @property urn the URN of the media to request.
+ * @property host The [IlHost] to use.
+ * @property urn The URN of the media to request.
  * @property vector The [Vector] to use.
  * @property forceSAM Force SAM usage.
- * @property ilLocation the [IlLocation] of the request.
+ * @property ilLocation The [IlLocation] of the request.
  */
 data class IlUrl(
     val host: IlHost,
@@ -27,7 +27,7 @@ data class IlUrl(
     }
 
     /**
-     * Uri
+     * [Uri] representation of this [IlUrl].
      */
     val uri: Uri = Uri.parse(host.baseHostUrl).buildUpon().apply {
         if (forceSAM) {
@@ -52,20 +52,20 @@ data class IlUrl(
         private const val PATH = "integrationlayer/2.1/mediaComposition/byUrn/"
 
         /**
-         * Convert an [Uri] into a valid [IlUrl].
+         * Converts an [Uri] into a valid [IlUrl].
          *
-         * @return a [IlUrl] or throw an [IllegalArgumentException] if the Uri can't be parse.
+         * @return An [IlUrl] or throws an [IllegalArgumentException] if the [Uri] can't be parsed.
          */
         fun Uri.toIlUrl(): IlUrl {
             val urn = lastPathSegment
+            require(urn.isValidMediaUrn()) { "Invalid URN $urn found in $this" }
             val host = IlHost.parse(toString())
-            require(urn.isValidMediaUrn()) { "Invalid urn $urn found in $this" }
-            requireNotNull(host) { "Invalid url $this" }
+            requireNotNull(host) { "Invalid URL $this" }
             val forceSAM = getQueryParameter(PARAM_FORCE_SAM)?.toBooleanStrictOrNull() == true || pathSegments.contains("sam")
             val ilLocation = getQueryParameter(PARAM_FORCE_LOCATION)?.let { IlLocation.fromName(it) }
             val vector = getQueryParameter(PARAM_VECTOR)?.let { Vector.fromLabel(it) } ?: Vector.MOBILE
 
-            return IlUrl(host = host, urn = checkNotNull(urn), vector, ilLocation = ilLocation, forceSAM = forceSAM)
+            return IlUrl(host = host, urn = checkNotNull(urn), vector = vector, ilLocation = ilLocation, forceSAM = forceSAM)
         }
     }
 }
diff --git a/...arbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/SRGAssetLoaderTest.kt b/...arbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/SRGAssetLoaderTest.kt
@@ -53,8 +53,17 @@ class SRGAssetLoaderTest {
     }
 
     @Test
-    fun testCanLoadMediaItem() {
+    fun testCanLoadAsset() {
+        assertTrue(assetLoader.canLoadAsset(SRGMediaItem("urn:rts:video:123")))
+    }
+
+    @Test
+    fun testCanLoadAsset_emptyMediaItem() {
         assertFalse(assetLoader.canLoadAsset(MediaItem.EMPTY))
+    }
+
+    @Test
+    fun testCanLoadAsset_invalidUri() {
         assertFalse(
             assetLoader.canLoadAsset(
                 MediaItem.Builder()
@@ -63,7 +72,6 @@ class SRGAssetLoaderTest {
                     .build()
             )
         )
-        assertTrue(assetLoader.canLoadAsset(SRGMediaItem("urn:rts:video:123")))
     }
 
     @Test(expected = IllegalStateException::class)

diff --git a/.../business/integrationlayer/IlHostTests.kt → ...e/business/integrationlayer/IlHostTest.kt b/.../business/integrationlayer/IlHostTests.kt → ...e/business/integrationlayer/IlHostTest.kt
@@ -12,17 +12,23 @@ import kotlin.test.assertEquals
 import kotlin.test.assertNull
 
 @RunWith(AndroidJUnit4::class)
-class IlHostTests {
+class IlHostTest {
 
     @Test
-    fun `Check parsing IlHost from String`() {
-        var host = IlHost.parse("https://il.srgssr.ch/somePath/andPath/?withParameters=45")
+    fun `parse prod IlHost`() {
+        val host = IlHost.parse("https://il.srgssr.ch/somePath/andPath/?withParameters=45")
         assertEquals(IlHost.PROD, host)
+    }
 
-        host = IlHost.parse("https://il-test.srgssr.ch/somePath/andPath/?withParameters=45")
+    @Test
+    fun `parse test IlHost`() {
+        val host = IlHost.parse("https://il-test.srgssr.ch/somePath/andPath/?withParameters=45")
         assertEquals(IlHost.TEST, host)
+    }
 
-        host = IlHost.parse("https://il-stage.srgssr.ch/somePath/andPath/?withParameters=45")
+    @Test
+    fun `parse stage IlHost`() {
+        val host = IlHost.parse("https://il-stage.srgssr.ch/somePath/andPath/?withParameters=45")
         assertEquals(IlHost.STAGE, host)
     }
 

diff --git a/...re-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlUrlTest.kt b/...re-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlUrlTest.kt
@@ -19,26 +19,28 @@ import kotlin.test.assertEquals
 class IlUrlTest {
 
     @Test(expected = IllegalArgumentException::class)
-    fun `toIlUrl throw error when not an url`() {
+    fun `toIlUrl throws an error when not an url`() {
         Uri.parse("yolo").toIlUrl()
     }
 
     @Test(expected = IllegalArgumentException::class)
-    fun `toIlUrl throw error with invalid il host name`() {
-        Uri.parse("https://il-foo.srg.ch/media/ByUrn/1234").toIlUrl()
+    fun `toIlUrl throws an error with invalid il host name`() {
+        Uri.parse("https://il-foo.srg.ch/media/ByUrn/urn:rts:video:123").toIlUrl()
     }
 
     @Test(expected = IllegalArgumentException::class)
-    fun `toIlUrl throw error with invalid urn`() {
+    fun `toIlUrl throws an error with invalid urn`() {
         Uri.parse("${IlHost.PROD.baseHostUrl}/integrationlayer/2.1/mediaComposition/byUrn/").toIlUrl()
     }
 
     @Test
     fun `toIlUrl correctly filled`() {
         val host = IlHost.PROD
         val urn = "urn:rts:video:1234"
-        val uri = Uri.parse("${host.baseHostUrl}/sam/integrationlayer/2.1/mediaComposition/byUrn/$urn?vector=TVPLAY&forceLocation=WW")
-        val expected = IlUrl(host = host, urn = urn, vector = Vector.TV, forceSAM = true, ilLocation = IlLocation.WW)
+        val vector = Vector.TV
+        val ilLocation = IlLocation.WW
+        val uri = Uri.parse("${host.baseHostUrl}/sam/integrationlayer/2.1/mediaComposition/byUrn/$urn?vector=$vector&forceLocation=$ilLocation")
+        val expected = IlUrl(host = host, urn = urn, vector = vector, forceSAM = true, ilLocation = ilLocation)
         assertEquals(expected, uri.toIlUrl())
     }
 
@@ -49,31 +51,34 @@ class IlUrlTest {
 
     @Test
     fun `ILUrl create correct uri with default parameters`() {
-        val uri = Uri.parse(
-            "${IlHost.PROD.baseHostUrl}/integrationlayer/2.1/mediaComposition/byUrn/" +
-                "urn:rts:video:1234?vector=${Vector.MOBILE}&onlyChapters=true"
-        )
-        val ilUrl = IlUrl(host = IlHost.PROD, urn = "urn:rts:video:1234", vector = Vector.MOBILE)
+        val host = IlHost.PROD
+        val urn = "urn:rts:video:1234"
+        val vector = Vector.MOBILE
+        val uri = Uri.parse("${host.baseHostUrl}/integrationlayer/2.1/mediaComposition/byUrn/$urn?vector=$vector&onlyChapters=true")
+        val ilUrl = IlUrl(host = host, urn = urn, vector = vector)
         assertEquals(uri, ilUrl.uri)
     }
 
     @Test
     fun `ILUrl create correct uri with forceSAM`() {
-        val uri = Uri.parse(
-            "${IlHost.PROD.baseHostUrl}/sam/integrationlayer/2.1/mediaComposition/byUrn/" +
-                "urn:rts:video:1234?forceSAM=true&vector=${Vector.MOBILE}&onlyChapters=true"
-        )
-        val ilUrl = IlUrl(host = IlHost.PROD, urn = "urn:rts:video:1234", vector = Vector.MOBILE, forceSAM = true)
+        val host = IlHost.PROD
+        val urn = "urn:rts:video:1234"
+        val vector = Vector.MOBILE
+        val uri = Uri.parse("${host.baseHostUrl}/sam/integrationlayer/2.1/mediaComposition/byUrn/$urn?forceSAM=true&vector=$vector&onlyChapters=true")
+        val ilUrl = IlUrl(host = host, urn = urn, vector = vector, forceSAM = true)
         assertEquals(uri, ilUrl.uri)
     }
 
     @Test
     fun `ILUrl create correct uri with ilLocation`() {
+        val host = IlHost.PROD
+        val urn = "urn:rts:video:1234"
+        val vector = Vector.MOBILE
+        val ilLocation = IlLocation.WW
         val uri = Uri.parse(
-            "${IlHost.PROD.baseHostUrl}/integrationlayer/2.1/mediaComposition/byUrn/" +
-                "urn:rts:video:1234?forceLocation=WW&vector=${Vector.MOBILE}&onlyChapters=true"
+            "${host.baseHostUrl}/integrationlayer/2.1/mediaComposition/byUrn/$urn?forceLocation=$ilLocation&vector=$vector&onlyChapters=true"
         )
-        val ilUrl = IlUrl(host = IlHost.PROD, urn = "urn:rts:video:1234", vector = Vector.MOBILE, ilLocation = IlLocation.WW)
+        val ilUrl = IlUrl(host = host, urn = urn, vector = vector, ilLocation = ilLocation)
         assertEquals(uri, ilUrl.uri)
     }
 }