Skip to content

Usage with Java

Overview

PokeKotlin is a Kotlin Multiplatform library that compiles to JVM bytecode, making it compatible with Java projects. The library provides both asynchronous (CompletableFuture-based) and blocking APIs for Java interoperability.

Installation

Gradle

This library is published via Maven Central, and snapshot builds of main are additionally available on GitHub Packages.

The latest release is v3.0.0-pre4. In your Gradle build script, add:

build.gradle
dependencies {
    implementation 'co.pokeapi.pokekotlin:pokekotlin-jvm:3.0.0-pre4'
}

Or if using Kotlin DSL:

build.gradle.kts
dependencies {
    implementation("co.pokeapi.pokekotlin:pokekotlin-jvm:3.0.0-pre4")
}

Warning

The published documentation is for the latest release, and may not match the snapshot version. If using snapshots, always refer to the latest source code for the most accurate information.

First, follow GitHub's guide for authenticating to GitHub Packages. Your build.gradle should have something like this:

build.gradle
repositories {
    maven {
        url = "https://maven.pkg.github.com/pokeapi/pokekotlin"
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("GH_USERNAME")
            password = project.findProperty("gpr.key") ?: System.getenv("GH_TOKEN")
        }
    }
}

The latest snapshot is v3.0.1-SNAPSHOT. Add the dependency:

build.gradle
dependencies {
    implementation 'co.pokeapi.pokekotlin:pokekotlin-jvm:3.0.1-SNAPSHOT'
}

Maven

The latest release is v3.0.0-pre4. In your pom.xml, add:

pom.xml
<dependency>
    <groupId>co.pokeapi.pokekotlin</groupId>
    <artifactId>pokekotlin-jvm</artifactId>
    <version>3.0.0-pre4</version>
</dependency>

Warning

The published documentation is for the latest release, and may not match the snapshot version. If using snapshots, always refer to the latest source code for the most accurate information.

First, configure GitHub Packages authentication in your settings.xml or pom.xml:

pom.xml
<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/pokeapi/pokekotlin</url>
    </repository>
</repositories>

The latest snapshot is v3.0.1-SNAPSHOT. Add the dependency:

pom.xml
<dependency>
    <groupId>co.pokeapi.pokekotlin</groupId>
    <artifactId>pokekotlin-jvm</artifactId>
    <version>3.0.1-SNAPSHOT</version>
</dependency>

Usage

For basic usage, use the global PokeApi.Default instance.

For asynchronous usage with CompletableFuture:

public class AsyncExample {
  public static void main(String[] args) {
    // Get a list of Pokémon species
    PokeApi.Default.getPokemonSpeciesListAsync(0, 10).thenAccept(list -> {
      for (NamedHandle<PokemonSpecies> handle : list.getResults()) {
        // Get each species by its handle
        PokeApi.Default.getAsync(handle).thenAccept(species ->
          System.out.println("Found: " + species)
        ).exceptionally(e -> {
          System.err.println("Error fetching species: " + e.getMessage());
          e.printStackTrace();
          return null;
        });
      }
    }).exceptionally(e -> {
      System.err.println("Error fetching species list: " + e.getMessage());
      e.printStackTrace();
      return null;
    });
  }
}

Blocking API

For synchronous/blocking usage:

public class BlockingExample {
  public static void main(String[] args) {
    try {
      // Get a list of Pokémon species
      PaginatedList<PokemonSpecies> list = PokeApi.Default.getPokemonSpeciesListBlocking(0, 10);

      for (Handle<PokemonSpecies> handle : list.getResults()) {
        // Get each species by its handle
        PokemonSpecies species = PokeApi.Default.getBlocking(handle);
        System.out.println("Found: " + species);
      }
    } catch (Exception e) {
      System.err.println("Error: " + e.getMessage());
      e.printStackTrace();
    }
  }
}

Further details

Every PokeApi endpoint has a corresponding asynchronous and blocking method in the PokeApi instance. By default, the client will connect to the official https://pokeapi.co/ instance and cache results in memory. To customize the client, you can create your own instance of PokeApi.Custom.

For further details, see the Kotlin API Reference. Any function like suspend fun getExample() available in the Kotlin API has corresponding Java APIs like CompletableFuture<Example> getExampleAsync() for asynchronous access, or Example getExampleBlocking() for synchronous access.