package org.apidesign.apifest08.currency;

 import java.math.BigDecimal;

 import java.util.Currency;

 import java.util.Set;

 /**

  * Convert between two currencies.

  *

  * @author D'Arcy Smith

  * @version 1.0

  */

 public interface Convertor

 {

     /**

      * Convert an amount from one currency to another.

      * 

      * @param from the currency to convert from.

      * @param to the currency to convert to.

      * @param amount the amount to convert.

      * @return the converted amount.

      * @throws IllegalArgumentException if any of the arguments are null.

      * @throws InvalidConversionException if either from or to are not valid for the convertor.

      */

     BigDecimal convert(Currency   from, 

                        Currency   to, 

                        BigDecimal amount)

         throws InvalidConversionException;

     /**

      * Check to see if converting between the two currencies is possible.

      *

      * @param from the currency to convert from.

      * @param to the currency to convert to.

      * @return true if the conversion is possible.

      */

     boolean canConvert(Currency from, Currency to);

     /**

      * Get the currencies that the convertor supports.  Just because a currency is

      * supported does not mean that canConvert will return true.

      * 

      * @return the supported currencies.

      */

     Set<Currency> getCurrencies();

     /**

      * Get the conversion rate between two currencies.

      * 

      * @param from the currency to convert from.

      * @param to the currency to convert to.

      * @return the conversion rate between the two currencies.

      * @throws InvalidConversionException if canConvert would return false.

      */

     BigDecimal getConversionRate(final Currency from, final Currency to)

         throws InvalidConversionException;

 }