Package net.thauvin.erik.frankfurter

Class Frankfurter

java.lang.Object

net.thauvin.erik.frankfurter.Frankfurter

public final class Frankfurter
extends Object

Client for the Frankfurter.dev exchange rates API.

Provides methods to fetch currency metadata, providers, and exchange rates. All calls are blocking. Instances are thread-safe and reusable.

Timeouts: 5s connect timeout, 10s request timeout by default. Both must be positive.

See Also:

• Frankfurter.dev API

Constructor Summary

Constructors

Constructor	Description
Frankfurter()	Creates a new client using the default API endpoint, default HttpClient with 5s connect timeout, and 10s request timeout.
Frankfurter(HttpClient client, URI baseUri)	Creates a new client using the given HTTP client and base URI with default 10s request timeout.
Frankfurter(HttpClient client, URI baseUri, Duration requestTimeout)	Creates a new client using the given HTTP client, base URI, and request timeout.
Frankfurter(URI baseUri)	Creates a new client using the given base URI, default HttpClient with 5s connect timeout, and 10s request timeout.
Frankfurter(Duration requestTimeout)	Creates a new client using the default API endpoint and connect timeout, with a custom request timeout.
Frankfurter(Duration connectTimeout, Duration requestTimeout)	Creates a new client using the default API endpoint with custom connect and request timeouts.

Method Summary

Modifier and Type	Method	Description
URI	getBaseUri()	Returns the base API URI used by this client.
HttpClient	getClient()	Returns the underlying HttpClient.
Optional<Duration>	getConnectTimeout()	Returns the connect timeout configured on the underlying HttpClient.
CurrenciesResult	getCurrencies()	Retrieves the list of supported currencies.
CurrencyResult	getCurrency(String code)	Retrieves metadata for a single currency.
CurrencyResult	getCurrency(CurrencyCode code)	Retrieves metadata for a single currency.
ProvidersResult	getProviders()	Retrieves the list of available rate providers.
RateResult	getRate(String base, String quote)	Retrieves a single exchange rate for the given currency pair.
RateResult	getRate(RateConfig config)	Retrieves a single exchange rate using the /rate/{base}/{quote} endpoint.
RateResult	getRate(CurrencyCode base, CurrencyCode quote)	Retrieves a single exchange rate for the given currency pair.
RatesResult	getRates()	Retrieves exchange rates using default configuration.
RatesResult	getRates(RatesConfig config)	Retrieves exchange rates using the /rates endpoint.
Duration	getRequestTimeout()	Returns the request timeout configured for this client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Frankfurter

public Frankfurter()

Creates a new client using the default API endpoint, default HttpClient with 5s connect timeout, and 10s request timeout.

Frankfurter

public Frankfurter(@NonNull
 Duration requestTimeout)

Creates a new client using the default API endpoint and connect timeout, with a custom request timeout.

Parameters:

requestTimeout - the request timeout (must be positive, not null)

Throws:

IllegalArgumentException - if requestTimeout is zero or negative

Frankfurter

public Frankfurter(@NonNull
 Duration connectTimeout,
 @NonNull
 Duration requestTimeout)

Creates a new client using the default API endpoint with custom connect and request timeouts.

Parameters:

connectTimeout - the connect timeout (must be positive, not null)

requestTimeout - the request timeout (must be positive, not null)

Throws:

IllegalArgumentException - if either timeout is zero or negative

Frankfurter

public Frankfurter(@NonNull
 URI baseUri)

Creates a new client using the given base URI, default HttpClient with 5s connect timeout, and 10s request timeout.

Parameters:

baseUri - the base API URI (must not be null)

Frankfurter

public Frankfurter(@NonNull
 HttpClient client,
 @NonNull
 URI baseUri)

Creates a new client using the given HTTP client and base URI with default 10s request timeout.

Note: The connect timeout is determined by the provided HttpClient. If the client was built without an explicit connect timeout, getConnectTimeout() will return an empty Optional.

Parameters:

client - the HTTP client to use (must not be null)

baseUri - the base API URI (must not be null)

Frankfurter

public Frankfurter(@NonNull
 HttpClient client,
 @NonNull
 URI baseUri,
 @NonNull
 Duration requestTimeout)

Creates a new client using the given HTTP client, base URI, and request timeout.

Note: The connect timeout is determined by the provided HttpClient. If the client was built without an explicit connect timeout, getConnectTimeout() will return an empty Optional.

Parameters:

client - the HTTP client to use (must not be null)

baseUri - the base API URI (must not be null)

requestTimeout - the request timeout (must be positive, not null)

Throws:

IllegalArgumentException - if requestTimeout is zero or negative

Method Details

getBaseUri

@NonNull
public URI getBaseUri()

Returns the base API URI used by this client.

Returns:

the base URI (never null)

getClient

@NonNull
public HttpClient getClient()

Returns the underlying HttpClient.

Returns:

the HTTP client (never null)

getConnectTimeout

@NonNull
public Optional<Duration> getConnectTimeout()

Returns the connect timeout configured on the underlying HttpClient.

Returns an empty Optional if the HttpClient was built without an explicit connect timeout, which means connections may block indefinitely.

Returns:

the connect timeout, or empty if not configured

getCurrencies

@NonNull
public CurrenciesResult getCurrencies()
                               throws IOException,
InterruptedException

Retrieves the list of supported currencies.

Returns:

the currencies result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getCurrency

@NonNull
public CurrencyResult getCurrency(@NonNull
 String code)
                           throws IOException,
InterruptedException

Retrieves metadata for a single currency.

Parameters:

code - the ISO currency code (must not be null or blank)

Returns:

the currency result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getCurrency

@NonNull
public CurrencyResult getCurrency(@NonNull
 CurrencyCode code)
                           throws IOException,
InterruptedException

Retrieves metadata for a single currency.

Parameters:

code - the currency code (must not be null)

Returns:

the currency result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getProviders

@NonNull
public ProvidersResult getProviders()
                             throws IOException,
InterruptedException

Retrieves the list of available rate providers.

Returns:

the providers result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getRate

@NonNull
public RateResult getRate(@NonNull
 String base,
 @NonNull
 String quote)
                   throws IOException,
InterruptedException

Retrieves a single exchange rate for the given currency pair.

Parameters:

base - the base ISO currency code (must not be null or blank)

quote - the quote ISO currency code (must not be null or blank)

Returns:

the rate result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getRate

@NonNull
public RateResult getRate(@NonNull
 CurrencyCode base,
 @NonNull
 CurrencyCode quote)
                   throws IOException,
InterruptedException

Retrieves a single exchange rate for the given currency pair.

Parameters:

base - the base currency (must not be null)

quote - the quote currency (must not be null)

Returns:

the rate result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getRate

@NonNull
public RateResult getRate(@NonNull
 RateConfig config)
                   throws IOException,
InterruptedException

Retrieves a single exchange rate using the /rate/{base}/{quote} endpoint.

Parameters:

config - the rate configuration (must not be null)

Returns:

the rate result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getRates

@NonNull
public RatesResult getRates()
                     throws IOException,
InterruptedException

Retrieves exchange rates using default configuration.

Returns:

the rates result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getRates

@NonNull
public RatesResult getRates(@NonNull
 RatesConfig config)
                     throws IOException,
InterruptedException

Retrieves exchange rates using the /rates endpoint.

Parameters:

config - the rates configuration (must not be null)

Returns:

the rates result

Throws:

IOException - if a network error occurs or the request times out

InterruptedException - if the request is interrupted

getRequestTimeout

@NonNull
public Duration getRequestTimeout()

Returns the request timeout configured for this client.

Returns:

the request timeout (never null)