package org.apidesign.apifest08.currency;

 import java.util.*;

 /**

  * CurrencyConversionService provides methods necessary for construction all necessary currency

  * conversion-related classes.

  */

 public interface CurrencyConverterProvider {

 	/**

 	 * Convenience method for getConverter(amount1, Currency.getInstance(currency1));

 	 *

 	 * @param amount1 amount of the money in the currency1

 	 * @param currency1 one of the supported currencies

 	 * @param amount2 amount of the money in the currency2

 	 * @param currency2 one of the supported currencies

 	 * @return converter able to convert between the two specified currencies

 	 * @throws IllegalArgumentException if any of the amount values is not positive

 	 * @throws CurrencyNotAvailableException thrown when one of the currencies is not available

 	 */

 	CurrencyConverter getConverter(double amount1, /*@NotNull*/ String currency1,

 								   double amount2, /*@NotNull*/ String currency2)

 			throws IllegalArgumentException, CurrencyNotAvailableException;

 	/**

 	 * Retrieves converter that is capable of converting values between currency1 and currency2.

 	 * The exchange is specified in easy to understand way. By specifying values in two currencies that

 	 * are equal. For example CurrencyConverter.getConverter(25, "CZK", 1, "EUR"); means 25CKZ is equal to 1EUR.

 	 * This enables user to use this method without having to calculate anything. In general this can be

 	 * expressed by formula amount1[currency1] = amount2[currency2].

 	 *

 	 * @param amount1 amount of the money in the currency1

 	 * @param currency1 one of the supported currencies

 	 * @param amount2 amount of the money in the currency2

 	 * @param currency2 one of the supported currencies

 	 * @return converter able to convert between the two specified currencies

 	 * @throws IllegalArgumentException if any of the amount values is not positive

 	 * @throws CurrencyNotAvailableException thrown when one of the currencies is not available

 	 */

 	CurrencyConverter getConverter(double amount1, /*@NotNull*/ Currency currency1,

 								   double amount2, /*@NotNull*/ Currency currency2)

 			throws IllegalArgumentException, CurrencyNotAvailableException;

 	/**

 	 * Creates a new converter that is able to convert between all specified currencies. The converter

 	 * may optionally support additional currencies that were not specified.

 	 *

 	 * @param currencies that the converter should be created for

 	 * @return converter able to convert between all specified currencies

 	 * @throws CurrencyNotAvailableException thrown when one of the currencies is not available

 	 * @throws NullPointerException if any of the specified currencies is null of the array is null

 	 */

 	CurrencyConverter getConverter(/*@NotNull*/ Currency... currencies)

 			throws CurrencyNotAvailableException, NullPointerException;

 	/**

 	 * Convenient method for getConverter(Currency...)

 	 *

 	 * @param currencies that the converter should be created for

 	 * @return converter able to convert between all specified currencies

 	 * @throws CurrencyNotAvailableException thrown when one of the currencies is not available

 	 * @throws NullPointerException if any of the specified currencies is null, or the array is null

 	 * @throws IllegalArgumentException if any of the specified currencies is not a valid ISO code

 	 */

 	CurrencyConverter getConverter(/*@NotNull*/ String... currencies)

 			throws CurrencyNotAvailableException, IllegalArgumentException, NullPointerException;

 }