1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/task4/solution07/src/org/apidesign/apifest08/currency/Convertor.java	Sat Oct 11 23:38:46 2008 +0200
     1.3 @@ -0,0 +1,109 @@
     1.4 +package org.apidesign.apifest08.currency;
     1.5 +
     1.6 +import java.util.Currency;
     1.7 +
     1.8 +/** This is the skeleton class for your API. You need to make it public, so
     1.9 + * it is accessible to your client code (currently in Task1Test.java) file.
    1.10 + * <p>
    1.11 + * Feel free to create additional classes or rename this one, just keep all
    1.12 + * the API and its implementation in this package. Do not spread it outside
    1.13 + * to other packages.
    1.14 + */
    1.15 +public interface Convertor {
    1.16 +    
    1.17 +    /**
    1.18 +     * Converts by taking a request and producing a response.
    1.19 +     * If a convertor finds it cannot perform the requested conversion,
    1.20 +     * it should return a non-null {@link ConversionResult} that has null {@link ConversionResult#getNetAmount()}.
    1.21 +     * A convertor must not convert to a different currency than the one specified in the request.
    1.22 +     * <p>
    1.23 +     * When the need comes to extend the semantics, one subclasses the ConversionRequest and/or ConversionResult classes.
    1.24 +     * <p>
    1.25 +     * This method can be called as many times as you like.
    1.26 +     * A {@link Convertor} shall be considered immutable wrt calls to {@link #convert(org.apidesign.apifest08.currency.Convertor.ConversionRequest).
    1.27 +     * This method of a single {@link Convertor} can be called from many threads concurrently.
    1.28 +     * @param req the conversion request; mustn't be null
    1.29 +     * @return the result of carrying out the conversion request; never null
    1.30 +     * @throws IllegalRequestSubtypeException when the particular implementation cannot handle a specific ConversionRequest type
    1.31 +     */
    1.32 +    public ConversionResult convert( final ConversionRequest req ) throws IllegalRequestSubtypeException;
    1.33 +
    1.34 +    /**
    1.35 +     * The request for converting a monetary amout into another currency.
    1.36 +     * Immutable.
    1.37 +     */
    1.38 +    public class ConversionRequest {
    1.39 +        
    1.40 +        private final MonetaryAmount srcAmount;
    1.41 +        private final Currency tgtCurrency;
    1.42 +
    1.43 +        /**
    1.44 +         * A request to convert srcAmount into tgtCurrency.
    1.45 +         * @param srcAmount the source amount; must not be null
    1.46 +         * @param tgtCurrency the currency we want it in afterwards; must not be null
    1.47 +         */
    1.48 +        public ConversionRequest( final MonetaryAmount srcAmount, final Currency tgtCurrency ) {
    1.49 +            this.srcAmount = srcAmount;
    1.50 +            this.tgtCurrency = tgtCurrency;
    1.51 +            if ( srcAmount == null ) {
    1.52 +                throw new NullPointerException( "The source amount" );
    1.53 +            }
    1.54 +            if ( tgtCurrency == null ) {
    1.55 +                throw new NullPointerException( "The target currency" );
    1.56 +            }
    1.57 +            if ( srcAmount.getCurrency().equals( tgtCurrency ) ) {
    1.58 +                throw new IllegalArgumentException( "Cannot request conversion from " + srcAmount.getCurrency() + " to " + tgtCurrency );
    1.59 +            }
    1.60 +        }
    1.61 +
    1.62 +        /**
    1.63 +         * The source amount.
    1.64 +         */
    1.65 +        public MonetaryAmount getSrcAmount() {
    1.66 +            return srcAmount;
    1.67 +        }
    1.68 +
    1.69 +        /**
    1.70 +         * The target currency.
    1.71 +         */
    1.72 +        public Currency getTgtCurrency() {
    1.73 +            return tgtCurrency;
    1.74 +        }
    1.75 +        
    1.76 +    }
    1.77 +    
    1.78 +    /**
    1.79 +     * The result of converting a monetary amount into another currency.
    1.80 +     * For now it records just the net amount one recieves from the conversion.
    1.81 +     * Immutable.
    1.82 +     * <p>
    1.83 +     * <b>Extension note:</b> 
    1.84 +     * Other items can be added further down the road, as the need for them arises.
    1.85 +     * These items might provide info on other aspects of the conversion,
    1.86 +     * such as the fee or a reason why the conversion might not be admissible.
    1.87 +     */
    1.88 +    public class ConversionResult {
    1.89 +        
    1.90 +        private final MonetaryAmount netAmount;
    1.91 +        
    1.92 +        /**
    1.93 +         * A new conversion result.
    1.94 +         * @param netAmount the amount one recieves from the conversion; 
    1.95 +         * null means the conversion was not admissible
    1.96 +         */
    1.97 +        public ConversionResult( final MonetaryAmount netAmount ) {
    1.98 +            this.netAmount = netAmount;
    1.99 +        }
   1.100 +        
   1.101 +        /**
   1.102 +         * The amount one recieves from the conversion.
   1.103 +         * If null, the conversion is not admissible.
   1.104 +         * @return the amount
   1.105 +         */
   1.106 +        public MonetaryAmount getNetAmount() {
   1.107 +            return netAmount;
   1.108 +        }
   1.109 +        
   1.110 +    }
   1.111 +    
   1.112 +}