DOCSEARCHbyAlgolia
Submit Docs

themoviedbapi Java Wrapper

repository·master·Indexed 43 days ago

https://github.com/c-eg/themoviedbapi

A Java wrapper for the TheMovieDB (TMdB) JSON API that provides structured access to movie and TV content databases. It includes support for the 'Append to Response' feature, custom HTTP client implementation via the TmdbRequestExecutor interface, and comprehensive exception handling through TmdbException and TmdbResponseException.

Tokens
2.1K
Snippets
11
Records
11
Agent score
5%

What's inside themoviedbapi

  1. How 'Append to Response' works

    master

    The TMdB API allows you to include additional related data in a single request using the 'Append to Response' feature. This wrapper mimics that scheme.

    If you call a method for a model that has fields for appendable responses (like getImages()) without providing the corresponding MovieAppendToResponse parameter in the initial request, the field will return null. To populate these fields, you must pass the appropriate enum values to the request method.

    TmdbMovies tmdbMovies = tmdbApi.getMovies();

// This will return null because IMAGES was not appended
MovieDb movie = tmdbMovies.getDetails(5353, "en-US");
Images images = movie.getImages(); 

// This will NOT be null because IMAGES was appended
MovieDb movieWithImages = tmdbMovies.getDetails(5353, "en-US", MovieAppendToResponse.IMAGES);
Images imagesFound = movieWithImages.getImages();

// You can also append multiple values or all available values
MovieDb movieWithMany = tmdbMovies.getDetails(5353, "en-US", MovieAppendToResponse.IMAGES, MovieAppendToResponse.VIDEOS);
MovieDb movieWithAll = tmdbMovies.getDetails(5353, "en-US", MovieAppendToResponse.values());

  2. Publish a snapshot to Maven Central

    master

    Snapshots are deployed directly via maven-publish to the Central Portal snapshot repository. They are not signed or validated. To publish a snapshot, set the version in build.gradle.kts to include the -SNAPSHOT suffix (e.g., 2.7.0-SNAPSHOT) and push to master.

    To trigger the deployment, you can either:

    1. Push a tag matching the snapshot version (e.g., v2.7.0-SNAPSHOT).
    2. Manually run the Publish Snapshot to Maven Central workflow from the GitHub Actions tab.
    # 1. Update build.gradle.kts to a -SNAPSHOT value (e.g., 2.7.0-SNAPSHOT)
# 2. Commit and push to master
# 3. Trigger via tag:
git tag v2.7.0-SNAPSHOT
git push origin v2.7.0-SNAPSHOT

  4. Release a new version to Maven Central

    master

    Releases are automated via GitHub Actions and triggered by pushing a version tag. The process involves updating the version in build.gradle.kts and pushing a corresponding git tag. The workflow automatically stages artifacts, GPG-signs them using JReleaser, deploys to Maven Central, and creates a GitHub release with an auto-generated changelog.

    Important: The git tag must match the version in build.gradle.kts. Tags with a -SNAPSHOT suffix are ignored by the release workflow and are instead handled by the snapshot workflow.

    # 1. Update build.gradle.kts to the release version (e.g., 2.7.0)
# 2. Commit and push to master
# 3. Create and push the tag
git tag v2.7.0
git push origin v2.7.0

  5. Initialize the TmdbApi client

    master

    To use the library, you must first obtain a TMdB API key. Ensure you use the API Read Access Token provided by TMdB. You can then instantiate the uk.co.conoregan.themoviedbapi.TmdbApi class using this token. By default, it uses a built-in HTTP client backed by java.net.http.HttpClient.

    TmdbApi tmdbApi = new TmdbApi("<apikey>");

  6. Handle TMdbExceptions and response codes

    master

    Every API method can throw a uk.co.conoregan.themoviedbapi.tools.TmdbException.

    • Catch uk.co.conoregan.themoviedbapi.tools.TmdbResponseException to handle cases where the TMdB API returned an unsuccessful status code (e.g., authentication failure). You can use exception.getResponseCode() to inspect the specific uk.co.conoregan.themoviedbapi.tools.TmdbResponseCode.
    • Catch uk.co.conoregan.themoviedbapi.tools.TmdbException for other unknown-cause exceptions.
    TmdbMovies tmdbMovies = tmdbApi.getMovies();

try {
    AccountStates accountStates = tmdbMovies.getAccountStates(-1, "accountId", null);
}
catch (TmdbResponseException exception) {
    TmdbResponseCode responseCode = exception.getResponseCode();
    // handle unsuccessful TMdB response code
}
catch (TmdbException exception) {
    // handle unknown-cause exception
}

  7. Configure Proguard / R8 rules for model minification

    master

    To prevent model classes from being stripped or renamed during minification, add the following rule to your proguard-rules.pro file. This ensures the classes in the uk.co.conoregan.themoviedbapi.model package are preserved.

    -keep class uk.co.conoregan.themoviedbapi.model.** { *; }

  8. Get movie details

    master

    Access movie-related data through the getMovies() getter on the TmdbApi instance. You can then retrieve specific movie details using getDetails(id, language).

    TmdbMovies tmdbMovies = tmdbApi.getMovies();
MovieDb movie = tmdbMovies.getDetails(5353, "en-US");

  9. Export GPG keys for GitHub secrets

    master

    When configuring GPG_PUBLIC_KEY and GPG_SECRET_KEY for the release workflow, use the following commands to export the ASCII-armored contents of your keys:

    gpg --armor --export <key-id>            # -> GPG_PUBLIC_KEY
gpg --armor --export-secret-keys <key-id> # -> GPG_SECRET_KEY

  10. Use a custom HTTP client

    master

    If you want to use a different HTTP client instead of the default JDK-based one, implement the uk.co.conoregan.themoviedbapi.tools.TmdbRequestExecutor interface.

    Your implementation should perform the network call and return the raw response. If an error occurs (like an IOException), wrap it in a uk.co.conoregan.themoviedbapi.tools.TmdbException. The library handles the interpretation of TMdB status codes automatically. Pass your custom implementation to the TmdbApi constructor.

    // Implement TmdbRequestExecutor
TmdbApi tmdbApi = new TmdbApi(new CustomHttpClient());

  11. Required GitHub repository secrets for publishing

    master

    The release and snapshot workflows require specific credentials configured in Settings → Secrets and variables → Actions.

    Note that GPG signing uses JReleaser MEMORY mode, meaning the secrets must contain the ASCII-armored key contents, not file paths.

    | Secret | Used by | Description |
|---|---|---|
| `GPG_PUBLIC_KEY` | release | ASCII-armored public key **contents** |
| `GPG_SECRET_KEY` | release | ASCII-armored private key **contents** |
| `GPG_PASSPHRASE` | release | Passphrase for the private key |
| `MAVENCENTRAL_USERNAME` | release + snapshot | Sonatype Central Portal token username |
| `MAVENCENTRAL_PASSWORD` | release + snapshot | Sonatype Central Portal token password |