V3

.github/workflows/gradle.yml → .github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: build
+name: CI
 
 on:
   push:
@@ -9,6 +9,11 @@ on:
 permissions:
   contents: read
 
+# Cancel superseded runs on the same ref (e.g. rapid pushes or PR updates).
+concurrency:
+  group: build-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -27,4 +32,4 @@ jobs:
         uses: gradle/actions/setup-gradle@v5
 
       - name: Execute Gradle Build
-        run: ./gradlew clean build --scan
+        run: ./gradlew clean build

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release to Maven Central
+
+on:
+  push:
+    tags:
+      - 'v*'
+      - '!v*-SNAPSHOT'  # snapshot tags are handled by the snapshot workflow
+  workflow_dispatch:
+
+permissions:
+  contents: write  # required to create the GitHub release
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Setup Java
+        uses: actions/setup-java@v5
+        with:
+          java-version: 17
+          distribution: corretto
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v5
+
+      - name: Publish to local staging repository
+        run: ./gradlew clean publishMavenJavaPublicationToStagingRepository
+
+      - name: Deploy to Maven Central
+        run: ./gradlew jreleaserDeploy
+        env:
+          JRELEASER_GPG_PUBLIC_KEY: ${{ secrets.GPG_PUBLIC_KEY }}
+          JRELEASER_GPG_SECRET_KEY: ${{ secrets.GPG_SECRET_KEY }}
+          JRELEASER_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+          JRELEASER_MAVENCENTRAL_USERNAME: ${{ secrets.MAVENCENTRAL_USERNAME }}
+          JRELEASER_MAVENCENTRAL_PASSWORD: ${{ secrets.MAVENCENTRAL_PASSWORD }}
+
+      - name: Create GitHub release
+        if: startsWith(github.ref, 'refs/tags/')  # skip when running the workflow manually
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "${GITHUB_REF_NAME}" --generate-notes --verify-tag

.github/workflows/snapshot.yml

@@ -0,0 +1,32 @@
+name: Publish Snapshot to Maven Central
+
+on:
+  push:
+    tags: [ 'v*-SNAPSHOT' ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  snapshot:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Setup Java
+        uses: actions/setup-java@v5
+        with:
+          java-version: 17
+          distribution: corretto
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v5
+
+      - name: Publish snapshot to Central Portal
+        run: ./gradlew clean publishMavenJavaPublicationToCentralSnapshotsRepository
+        env:
+          MAVENCENTRAL_USERNAME: ${{ secrets.MAVENCENTRAL_USERNAME }}
+          MAVENCENTRAL_PASSWORD: ${{ secrets.MAVENCENTRAL_PASSWORD }}

README.md

@@ -9,30 +9,7 @@ The wrapper implements most, if not all, of the JSON API. However, because the A
 not be implemented, or current functionality may break. Please point this out by submitting an issue, or even better, just send us a pull 
 request!
 
-It's available via [Maven Central](https://central.sonatype.com/artifact/uk.co.conoregan/themoviedbapi). Just add it as dependency to your 
-project.
-
-<details open>
-<summary>Maven</summary>
-
-```xml
-<dependency>
-    <groupId>uk.co.conoregan</groupId>
-    <artifactId>themoviedbapi</artifactId>
-    <version>{version}</version>
-</dependency>
-```
-</details>
-
-<details>
-<summary>Gradle (Kotlin)</summary>
-
-```kotlin
-dependencies {
-    implementation("uk.co.conoregan:themoviedbapi:{version}")
-}
-```
-</details>
+It's available via [Maven Central](https://central.sonatype.com/artifact/uk.co.conoregan/themoviedbapi). Just add it as dependency to your project.
 
 ## Usage
 To register for a TMdB API key, click the [API link](https://www.themoviedb.org/settings/api) from within your account settings page. There are two types of API keys currently provided by TMdB, please ensure you are using the `API Read Access Token` key.
@@ -42,6 +19,9 @@ With this you can instantiate `info.movito.themoviedbapi.TmdbApi`, which has get
 TmdbApi tmdbApi = new TmdbApi("<apikey>");
 ```
 
+By default this uses the library's built-in HTTP client. If you would rather plug in your own, see
+[Using your own HTTP client](#using-your-own-http-client).
+
 ### Examples
 #### Get movie details
 ```java
@@ -78,7 +58,7 @@ MovieDb movie = tmdbMovies.getDetails(5353, "en-US", MovieAppendToResponse.value
 To find all methods that use append to response, see the `info.movito.themoviedbapi.tools.appendtoresponse.AppendToResponse` interface 
 implementations.
 
-### Exception Handling
+### Exception handling
 Every API method can throw a `info.movito.themoviedbapi.tools.TmdbException` if the request fails for any reason. You should catch this 
 exception and handle it appropriately.
 
@@ -106,6 +86,20 @@ catch (TmdbException exception) {
 We chose to throw exceptions rather than returning `null`, so you have more control over what you do with each failure case. E.g. with the
 example above, you may want to display an error message to the user about failing authentication.
 
+### Using your own HTTP client
+By default, `TmdbApi` uses the built-in `info.movito.themoviedbapi.tools.TmdbHttpClient`, which is backed by the JDK's
+`java.net.http.HttpClient`. If you would rather use a different HTTP client, you can provide your own
+implementation of the `info.movito.themoviedbapi.tools.TmdbRequestExecutor` interface.
+
+Your implementation only has to make the call and hand back the raw response. If the request fails (e.g. an `IOException`), wrap it in a 
+`info.movito.themoviedbapi.tools.TmdbException`. Interpreting TMdB status codes (e.g. mapping unsuccessful responses to exceptions) is handled by the library on top of your executor, so 
+you do not need to deal with that (see `info.movito.themoviedbapi.tools.TmdbApiClient` for more information).
+
+Then, simply pass your implementation to `TmdbApi` instead of the API key:
+```java
+TmdbApi tmdbApi = new TmdbApi(new CustomHttpClient());
+```
+
 ## Project Logging
 
 This project uses [SLF4J](http://www.slf4j.org) to abstract the logging in the project. To use the logging in your own

build.gradle.kts

@@ -2,7 +2,6 @@ plugins {
     `java-library`
     checkstyle
     `maven-publish`
-    signing
     id("io.github.gradle-nexus.publish-plugin") version "2.0.0"
     id("org.jreleaser") version "1.25.0"
 }
@@ -22,12 +21,14 @@ dependencies {
     // testing
     testImplementation(platform("org.junit:junit-bom:6.1.1"))
     testImplementation("org.junit.jupiter:junit-jupiter")
-    testRuntimeOnly("org.junit.platform:junit-platform-launcher")  // gradle bundled version is incompatible with 5.12
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")  // pin launcher to junit-bom; Gradle's bundled one lags the JUnit version
 
     testImplementation(platform("org.mockito:mockito-bom:5.23.0"))
     testImplementation("org.mockito:mockito-core")
     testImplementation("org.mockito:mockito-junit-jupiter")
 
+    testImplementation("org.wiremock:wiremock:3.13.2")
+
     // util
     compileOnly("org.projectlombok:lombok:1.18.46")
     annotationProcessor("org.projectlombok:lombok:1.18.46")
@@ -40,16 +41,37 @@ dependencies {
     implementation("com.fasterxml.jackson.core:jackson-databind")
 
     implementation("org.apache.commons:commons-lang3:3.20.0")
+
     testImplementation("commons-io:commons-io:2.22.0")
 }
 
 java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(17)
+    }
     withJavadocJar()
     withSourcesJar()
 }
 
 tasks.test {
-    useJUnitPlatform()
+    useJUnitPlatform {
+        excludeTags("integration")
+    }
+}
+
+tasks.register<Test>("integrationTest") {
+    description = "Runs integration tests (tagged with \"integration\")."
+    group = "verification"
+    useJUnitPlatform {
+        includeTags("integration")
+    }
+    testClassesDirs = sourceSets["test"].output.classesDirs
+    classpath = sourceSets["test"].runtimeClasspath
+    shouldRunAfter(tasks.test)
+}
+
+tasks.check {
+    dependsOn("integrationTest")
 }
 
 checkstyle {
@@ -80,14 +102,15 @@ publishing {
 
                 licenses {
                     license {
-                        name = "BSD"
+                        name = "BSD-2-Clause"
                         url = "https://github.com/c-eg/themoviedbapi/blob/master/LICENCE.txt"
                     }
                 }
 
                 scm {
-                    connection = "scm:git:github.com/c-eg/themoviedbapi.git"
-                    url = "https://github.com/c-eg/themoviedbapi.git"
+                    connection = "scm:git:https://github.com/c-eg/themoviedbapi.git"
+                    developerConnection = "scm:git:ssh://git@github.com/c-eg/themoviedbapi.git"
+                    url = "https://github.com/c-eg/themoviedbapi"
                 }
 
                 developers {
@@ -107,9 +130,21 @@ publishing {
         }
     }
     repositories {
+        // Local staging dir that JReleaser reads from for the signed release deploy.
         maven {
+            name = "staging"
             url = uri(layout.buildDirectory.dir("staging-deploy"))
         }
+
+        // Central Portal snapshot repository.
+        maven {
+            name = "centralSnapshots"
+            url = uri("https://central.sonatype.com/repository/maven-snapshots/")
+            credentials {
+                username = providers.environmentVariable("MAVENCENTRAL_USERNAME").orNull
+                password = providers.environmentVariable("MAVENCENTRAL_PASSWORD").orNull
+            }
+        }
     }
 }
 
@@ -118,9 +153,7 @@ jreleaser {
         pgp {
             active = org.jreleaser.model.Active.ALWAYS
             armored = true
-            mode = org.jreleaser.model.Signing.Mode.FILE
-            publicKey = "C:/gpg/public.pgp"
-            secretKey = "C:/gpg/private.pgp"
+            mode = org.jreleaser.model.Signing.Mode.MEMORY
         }
     }
     deploy {
@@ -136,20 +169,11 @@ jreleaser {
     }
 }
 
-if (project.hasProperty("signing.keyId") && project.hasProperty("signing.password") && project.hasProperty("signing.secretKeyRingFile")) signing {
-    sign(publishing.publications["mavenJava"])
-}
-
 tasks.javadoc {
-    if (JavaVersion.current().isJava9Compatible) {
-        (options as StandardJavadocDocletOptions).addBooleanOption("html5", true)
-    }
-}
-
-tasks {
-    javadoc {
-        options {
-            (this as CoreJavadocOptions).addBooleanOption("Xdoclint:none", true)
+    options {
+        (this as StandardJavadocDocletOptions).apply {
+            addBooleanOption("Xdoclint:none", true)
+            addBooleanOption("html5", true)
         }
     }
 }