japod@6: package org.apidesign.apifest08.currency;
japod@6: 
japod@6: 
japod@6: import java.math.BigDecimal;
japod@6: import java.util.Currency;
japod@35: import java.util.Set;
japod@6: 
japod@6: 
japod@6: /**
japod@6:  * Convert between two currencies.
japod@6:  *
japod@6:  * @author D'Arcy Smith
japod@6:  * @version 1.0
japod@6:  */
japod@17: public interface Convertor
japod@6: {
japod@6:     /**
japod@17:      * Convert an amount from one currency to another.
japod@6:      * 
japod@17:      * @param from the currency to convert from.
japod@17:      * @param to the currency to convert to.
japod@6:      * @param amount the amount to convert.
japod@6:      * @return the converted amount.
japod@17:      * @throws IllegalArgumentException if any of the arguments are null.
japod@17:      * @throws InvalidConversionException if either from or to are not valid for the convertor.
japod@6:      */
japod@17:     BigDecimal convert(Currency   from, 
japod@17:                        Currency   to, 
japod@17:                        BigDecimal amount)
japod@17:         throws InvalidConversionException;
japod@35: 
japod@35:     /**
japod@35:      * Check to see if converting between the two currencies is possible.
japod@35:      *
japod@35:      * @param from the currency to convert from.
japod@35:      * @param to the currency to convert to.
japod@35:      * @return true if the conversion is possible.
japod@35:      */
japod@35:     boolean canConvert(Currency from, Currency to);
japod@35: 
japod@35:     /**
japod@35:      * Get the currencies that the convertor supports.  Just because a currency is
japod@35:      * supported does not mean that canConvert will return true.
japod@35:      * 
japod@35:      * @return the supported currencies.
japod@35:      */
japod@35:     Set<Currency> getCurrencies();
japod@35: 
japod@35:     /**
japod@35:      * Get the conversion rate between two currencies.
japod@35:      * 
japod@35:      * @param from the currency to convert from.
japod@35:      * @param to the currency to convert to.
japod@35:      * @return the conversion rate between the two currencies.
japod@35:      * @throws InvalidConversionException if canConvert would return false.
japod@35:      */
japod@35:     BigDecimal getConversionRate(final Currency from, final Currency to)
japod@35:         throws InvalidConversionException;
japod@6: }