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 the Money.ExchangeRates behaviour. The default is Money.ExchangeRates.OpenExchangeRates

  • :callback_module defines a module that follows the Money.ExchangeRates.Callback behaviour whereby the function rates_retrieved/2 is invoked after every successful retrieval of exchange rates. The default is Money.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 is nil 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 the init/1 callback in the retriever module. See Money.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.

Link to this function get_latest_rates(config \\ default_config()) View Source

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.

Link to this function last_updated() View Source
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"}}
Link to this function latest_rates() View Source
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.

Link to this function rates_available?() View Source
rates_available?() :: boolean()

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

Link to this callback get_latest_rates(config) View Source
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}

Link to this callback init(config) View Source (optional)
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.

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.