api-client/com.gw2tb.gw2api.client

Package-level declarations

Types

AuthenticationStrategy

enum AuthenticationStrategy : Enum<AuthenticationStrategy>

An authentication strategy determines how to authenticate requests to the API.

CacheAccess

interface CacheAccess

Provides basic access to a response caching implementation.

DecodingResult

@JvmInline

value class DecodingResult<out T>

A discriminated union that encapsulates a successful outcome with a value of type T or a failure with an arbitrary Throwable exception. A schema mismatch is a special type of failure that may be partially recoverable.

Gw2ApiClient

expect class Gw2ApiClient @InternalGw2ApiClientApi constructor(httpClient: IHttpClient, host: String, authenticationStrategy: AuthenticationStrategy, cacheAccess: CacheAccess?, rateLimiter: RateLimiter?, json: Json, requestConfigurers: List<RequestConfigurer>)

A client that may be used to make requests to the official Guild Wars 2 API (or a mirror).

actual class Gw2ApiClient @InternalGw2ApiClientApi constructor(httpClient: IHttpClient, host: String, authenticationStrategy: AuthenticationStrategy, cacheAccess: CacheAccess?, rateLimiter: RateLimiter?, json: Json, requestConfigurers: List<RequestConfigurer>) : AutoCloseable

Gw2ApiClientBuilder

class Gw2ApiClientBuilder

An intermediate object for building Gw2ApiClient instances.

Gw2ApiClientConfigurer

fun interface Gw2ApiClientConfigurer

Configures a Gw2ApiClient.

Gw2ApiClientDefaults

object Gw2ApiClientDefaults

Defaults values for Gw2ApiClient instances.

Gw2ApiRequest

class Gw2ApiRequest<T>

An HTTP request against the Guild Wars 2 API.

Gw2ApiResponse

class Gw2ApiResponse<T>

An HTTP response from the Guild Wars 2 API.

Language

enum Language : Enum<Language>

A languages supported by the Guild Wars 2 API.

RateLimiter

interface RateLimiter

A RateLimiter provides logic necessary to limit the rate of execution of any sort of requests. For this purpose, a rate limiter distributes permits at a configurable rate. Permits can be acquired and do not have to be released.

RequestBuilder

class RequestBuilder<T>

An intermediate object for building RequestTemplate instances.

RequestConfigurer

fun interface RequestConfigurer

Configures a RequestTemplate.

RequestTemplate

data class RequestTemplate<T>

A template for a request that can be executed by an API client.

ResponseHeaders

@JvmInline

value class ResponseHeaders(headers: Map<String, List<String>>) : Map<String, List<String>>

The headers of a Response.

TokenBucketRateLimiter

class TokenBucketRateLimiter(bucketSize: Int = 300, refillDuration: Duration = 1.minutes) : RateLimiter

A RateLimiter implementation that uses the token bucket algorithm.

UnsafeQueryAuthentication

annotation class UnsafeQueryAuthentication

A marker class that is used enforce explicit consent for using AuthenticationStrategy.QUERY.

Functions

fold

fun <R, T> DecodingResult<T>.fold(onSuccess: (value: T) -> R, onFailure: (exception: Throwable) -> R): R

Returns the result of onSuccess for the encapsulated value if this instance represents success or the result of onFailure for the encapsulated Throwable if this instance represents failure.

fun <R, T> DecodingResult<T>.fold(onSuccess: (value: T) -> R, onSchemaMismatch: (JsonElement, exception: Throwable) -> R, onFailure: (exception: Throwable) -> R): R

Returns the result of onSuccess for the encapsulated value if this instance represents success, the result of onSchemaMismatch for the encapsulated JsonElement and Throwable if this instance represents a schema mismatch, or the result of onFailure for the encapsulated Throwable if this instance represents any other failure.

getOrDefault

inline fun <R, T : R> DecodingResult<T>.getOrDefault(defaultValue: R): R

Returns the encapsulated value if this instance represents success or the defaultValue if it is failure.

getOrElse

inline fun <R, T : R> DecodingResult<T>.getOrElse(onFailure: (exception: Throwable) -> R): R

Returns the encapsulated value if this instance represents success or the result of onFailure for the encapsulated Throwable exception if it is failure.

inline fun <R, T : R> DecodingResult<T>.getOrElse(onSchemaMismatch: (JsonElement, exception: Throwable) -> R, onFailure: (exception: Throwable) -> R): R

Returns the encapsulated value if this instance represents success, the result of onSchemaMismatch for the encapsulated JsonElement and Throwable if it is schema mismatch or the result of onFailure for the encapsulated Throwable if it is failure.

getOrThrow

inline fun <T> DecodingResult<T>.getOrThrow(): T

Returns the encapsulated value if this instance represents success or throws the encapsulated Throwable if it is failure.

Gw2ApiClient

@InternalGw2ApiClientApi

fun Gw2ApiClient(httpClient: IHttpClient, block: Gw2ApiClientConfigurer): Gw2ApiClient

Creates a new Gw2ApiClient using the provided IHttpClient and the given configuration.

map

inline fun <R, T> DecodingResult<T>.map(transform: (value: T) -> R): DecodingResult<R>

Returns the encapsulated result of the given transform function applied to the encapsulated value if this instance represents success or the original encapsulated Throwable if it is failure.

mapCatching

inline fun <R, T> DecodingResult<T>.mapCatching(transform: (value: T) -> R): DecodingResult<R>

Returns the encapsulated result of the given transform function applied to the encapsulated value if this instance represents success or the original encapsulated Throwable if it is failure.

onFailure

inline fun <T> DecodingResult<T>.onFailure(action: (exception: Throwable) -> Unit): DecodingResult<T>

Performs the given action on the encapsulated Throwable exception if this instance represents failure. Returns the receiver DecodingResult.

onSuccess

inline fun <T> DecodingResult<T>.onSuccess(action: (value: T) -> Unit): DecodingResult<T>

Performs the given action on the encapsulated value if this instance represents success. Returns the receiver DecodingResult.

recover

inline fun <R, T : R> DecodingResult<T>.recover(transform: (exception: Throwable) -> R): DecodingResult<R>

Returns the encapsulated result of the given transform function applied to the encapsulated Throwable exception if this instance represents failure or the original encapsulated value if it is success.

recoverCatching

inline fun <R, T : R> DecodingResult<T>.recoverCatching(transform: (exception: Throwable) -> R): DecodingResult<R>

tryRecoverPartially

fun <E> DecodingResult<List<E>>.tryRecoverPartially(json: Json = Json, deserializer: DeserializationStrategy<E>): List<DecodingResult<E>>

fun <K, V> DecodingResult<Map<K, V>>.tryRecoverPartially(json: Json = Json, keyDeserializer: DeserializationStrategy<K>, deserializer: DeserializationStrategy<V>): Map<K, DecodingResult<V>>

Tries to recover the response partially if the result represents a schema mismatch. If the result represents another failure, an IllegalStateException is thrown. Successful results are simply transformed.