From ad28c128ebb445e21912d12f26a9e5cfb44d71c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABtan=20Muller?= Date: Tue, 17 Dec 2024 10:17:39 +0100 Subject: [PATCH] Documentation update --- .../pillarbox/core/business/SRGMediaItem.kt | 16 +++---- .../integrationlayer/service/IlHost.kt | 10 +++-- .../integrationlayer/service/IlUrl.kt | 18 ++++---- .../core/business/SRGAssetLoaderTest.kt | 12 +++++- .../{IlHostTests.kt => IlHostTest.kt} | 16 ++++--- .../business/integrationlayer/IlUrlTest.kt | 43 +++++++++++-------- 6 files changed, 68 insertions(+), 47 deletions(-) rename pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/{IlHostTests.kt => IlHostTest.kt} (67%) 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 index dc00bdce8..e26d766e2 100644 --- 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/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlHost.kt b/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlHost.kt index 1fef951d0..d2b0ab610 100644 --- a/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlHost.kt +++ b/pillarbox-core-business/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/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlUrl.kt b/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlUrl.kt index 0c7e51cd1..ff9e15e1b 100644 --- a/pillarbox-core-business/src/main/java/ch/srgssr/pillarbox/core/business/integrationlayer/service/IlUrl.kt +++ b/pillarbox-core-business/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/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/SRGAssetLoaderTest.kt b/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/SRGAssetLoaderTest.kt index fc6da43f1..63a9c505a 100644 --- a/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/SRGAssetLoaderTest.kt +++ b/pillarbox-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/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlHostTests.kt b/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlHostTest.kt similarity index 67% rename from pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlHostTests.kt rename to pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlHostTest.kt index b565a1fa5..6bb3dcccb 100644 --- a/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlHostTests.kt +++ b/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/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/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlUrlTest.kt b/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlUrlTest.kt index 4a6941f10..d63ca0726 100644 --- a/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlUrlTest.kt +++ b/pillarbox-core-business/src/test/java/ch/srgssr/pillarbox/core/business/integrationlayer/IlUrlTest.kt @@ -19,17 +19,17 @@ 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() } @@ -37,8 +37,10 @@ class IlUrlTest { 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) } }