Money v0.8.2 Money.ExchangeRates behaviour View Source
Implements a behaviour and functions to retrieve exchange rates from an exchange rate service.
Configuration for the exchange rate service is defined
in a Money.ExchangeRates.Config
struct. A default
configuration is returned by Money.ExchangeRates.default_config/0
.
The default configuration is:
config :ex_money,
exchange_rate_service: false,
exchange_rates_retrieve_every: 300_000,
delay_before_first_retrieval: 100,
api_module: Money.ExchangeRates.OpenExchangeRates,
callback_module: Money.ExchangeRates.Callback,
log_failure: :warn,
log_info: :info,
log_success: nil
These keys are are defined as follows:
:exchange_rate_service
is a boolean that determines whether to automatically start the exchange rate retrieval service. The default it false.:exchange_rates_retrieve_every
defines how often the exchange rates are retrieved in milliseconds. The default is 5 minutes (300,000 milliseconds):delay_before_first_retrieval
defines how quickly the retrieval service makes its first request for exchange rates. The default is 100 milliseconds. Any value that is not a positive integer means that no first retrieval is made. Retrieval will continue on interval defined by:retrieve_every
:api_module
identifies the module that does the retrieval of exchange rates. This is any module that implements theMoney.ExchangeRates
behaviour. The default isMoney.ExchangeRates.OpenExchangeRates
:callback_module
defines a module that follows the Money.ExchangeRates.Callback behaviour whereby the functionrates_retrieved/2
is invoked after every successful retrieval of exchange rates. The default isMoney.ExchangeRates.Callback
.:log_failure
defines the log level at which api retrieval errors are logged. The default is:warn
:log_success
defines the log level at which successful api retrieval notifications are logged. The default isnil
which means no logging.:log_info
defines the log level at which service startup messages are logged. The default is:info
.:retriever_options
is available for exchange rate retriever module developers as a place to add retriever-specific configuration information. This information should be added in theinit/1
callback in the retriever module. SeeMoney.ExchangeRates.OpenExchangeRates.init/1
for an example.
Keys can also be configured to retrieve values from environment
variables. This lookup is done at runtime to facilitate deployment
strategies. If the value of a configuration key is
{:system, "some_string"}
then “some_string” is interpreted as
an environment variable name which is passed to System.get_env/2.
An example configuration might be:
config :ex_money,
exchange_rate_service: {:system, "RATE_SERVICE"},
exchange_rates_retrieve_every: {:system, "RETRIEVE_EVERY"},
Open Exchange Rates
If you plan to use the provided Open Exchange Rates module
to retrieve exchange rates then you should also provide the additional
configuration key for app_id
:
config :ex_money,
open_exchange_rates_app_id: "your_app_id"
or configure it via environment variable:
config :ex_money,
open_exchange_rates_app_id: {:system, "OPEN_EXCHANGE_RATES_APP_ID"}
The default exchange rate retrieval module is provided in
Money.ExchangeRates.OpenExchangeRates
which can be used
as a example to implement your own retrieval module for
other services.
Managing the configuration at runtime
During exchange rate service startup, the function init/1
is called
on the configuration exchange rate retrieval module. This module is
expected to return an updated configuration allowing a developer to
customise how the configuration is to be managed. See the implementation
at Money.ExchangeRates.OpenExchangeRates.init/1
for an example.
Link to this section Summary
Functions
Returns the default configuration for the exchange rates retriever
Retrieves exchange rates from the configured exchange rate api module
Return the timestamp of the last successful retrieval of exchange rates or
{:error, reason}
if no timestamp is known
Return the latest exchange rates
Returns true
if exchange rates are available
and false otherwise
Forces retrieval of exchange rates
Callbacks
Invoked to return the latest exchange rates from the configured exchange rate retrieval service
Given the default configuration, returns an updated configuration at runtime during exchange rates service startup
Link to this section Functions
Returns the default configuration for the exchange rates retriever.
Retrieves exchange rates from the configured exchange rate api module.
This call is the public api to retrieve results from an external api service
or other mechanism implemented by an api module. This method is typically
called periodically by Money.ExchangeRates.Retriever.handle_info/2
but can
called at any time by other functions.
last_updated() :: {:ok, DateTime.t()} | {:error, {Exception.t(), binary()}}
Return the timestamp of the last successful retrieval of exchange rates or
{:error, reason}
if no timestamp is known.
Example
Money.ExchangeRates.last_updated
#> {:ok,
%DateTime{calendar: Calendar.ISO, day: 20, hour: 12, microsecond: {731942, 6},
minute: 36, month: 11, second: 6, std_offset: 0, time_zone: "Etc/UTC",
utc_offset: 0, year: 2016, zone_abbr: "UTC"}}
latest_rates() :: {:ok, Map.t()} | {:error, {Exception.t(), binary()}}
Return the latest exchange rates.
Returns:
{:ok, rates}
if exchange rates are successfully retrieved.rates
is a map of exchange rates.{:error, reason}
if no exchange rates can be returned.
Returns true
if exchange rates are available
and false otherwise.
Forces retrieval of exchange rates
Sends a message ot the exchange rate retrieval worker to request rates be retrieved.
This function does not return exchange rates, for that see
Money.ExchangeRates.latest_rates/0
.
Link to this section Callbacks
get_latest_rates(config :: Money.Config.t()) :: {:ok, Map.t()} | {:error, binary()}
Invoked to return the latest exchange rates from the configured exchange rate retrieval service.
config
is an%Money.ExchangeRataes.Config{}
struct
Returns {:ok, map_of_rates}
or {:error, reason}
init(config :: Money.Config.t()) :: Money.Config.t()
Given the default configuration, returns an updated configuration at runtime during exchange rates service startup.
This callback is optional. If the callback is not defined, the default
configuration returned by Money.ExchangeRates.default_config/0
is used.
config
is the configuration returned byMoney.ExchangeRates.default_config/0
The callback is expected to return a %Money.ExchangeRates.Config{}
struct
which may have been updated. The configuration key :retriever_options
is
available for any service-specific configuration.