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;

}