README.md

PokéFuture

A reactive PokéApi-Wrapper written in Java using Vert.x

Maintainers: Pascal Klaßen and Phil Träger

Download

Replace VERSION in the examples below with the latest stable release version.

Maven

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <repositories>
        <repository>
            <id>ossrh</id>
            <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>io.github.pascalklassen</groupId>
            <artifactId>poke-future</artifactId>
            <version>VERSION</version>
        </dependency>
    </dependencies>
</project>

Gradle Groovy DSL

repositories {
    maven {
        name 'ossrh'
        url 'https://s01.oss.sonatype.org/content/repositories/snapshots'
    }
}

dependencies {
    implementation 'io.github.pascalklassen:poke-future:VERSION'
}

Gradle Kotlin DSL

repositories {
    maven {
        name = "ossrh"
        url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots")
    }
}

dependencies {
    implementation("io.github.pascalklassen:poke-future:VERSION")
}

Getting Started

Fetch a single Pokémon

import io.github.pascalklassen.pokefuture.pokemon.Pokemon;

class Example {
    public static void main(String[] args) {
        Pokemon
                .fetch("bulbasaur") // Future<Pokemon>
                .onSuccess(pokemon -> System.out.println(pokemon.getName()))
                .onFailure(cause -> System.err.println(cause.getMessage()));
    }
}

Fetch a List of Pokémon

import io.github.pascalklassen.pokefuture.pokemon.Pokemon;
import io.github.pascalklassen.pokefuture.utility.common.APIResource;

class Example {
    public static void main(String[] args) {
        Pokemon
                .fetchList()
                // Future<NamedAPIResourceList<Pokemon>>
                .compose(APIResource::composeAll)
                // Future<List<Pokemon>>
                .onSuccess(pokemonList -> 
                        pokemonList.forEach(pokemon -> System.out.println(pokemon.getName())))
                .onFailure(cause -> System.err.println(cause.getMessage()));
    }
}

How it works

Model representation

To minimize the effort of learning a new API Structure, our goal was to represent a 1:1 Model of the official REST-PokéAPI. New Users can just look at the REST Model and immediately understand what methods they need to call on our Objects.

This seems quite handy, but it comes along the way with some code smells that we try to reduce as much as needed.

For example, the PokéAPI has some common Models such as APIResource, NamedAPIResource, APIResourceList and NamedAPIResourceList to reduce the number of data they need to send per request. The first two APIResource and NamedAPIResource both represent a link to a REST-Resource where you can request additional data. To counteract this drawback, we allow the User to chain their API calls in an asynchronous way with Future Composition.

This will look like this:

import io.github.pascalklassen.pokefuture.pokemon.Pokemon;

class Example {
    public static void main(String[] args) {
        Pokemon
                .fetch("bulbasaur")
                // PokemonSpecies is a NamedAPIResource, so you need to fetch it seperately
                .compose(pokemon -> pokemon.getSpecies().fetch())
                // PokemonColor is a NamedAPIResource, so you need to fetch it seperately
                .compose(species -> species.getColor().fetch())
                .onSuccess(color -> System.out.println("Bulbasaur is " + color.getName()))
                .onFailure(cause -> System.err.println(cause.getMessage()));
    }
}

Pokemon#getSpecies and PokemonSpecies#getColor both return a NamedAPIResource, in fact you can just see this in the official documentation, on which you can invoke the APIResource#fetch Method that returns a Future Object that provides you the results as its underlying process is completed.