1 package org.apidesign.apifest08.currency;
3 import java.util.Currency;
5 /** This is the skeleton class for your API. You need to make it public, so
6 * it is accessible to your client code (currently in Task1Test.java) file.
8 * Feel free to create additional classes or rename this one, just keep all
9 * the API and its implementation in this package. Do not spread it outside
12 public interface Convertor {
15 * Converts by taking a request and producing a response.
16 * If a convertor finds it cannot perform the requested conversion,
17 * it should return a non-null {@link ConversionResult} that has null {@link ConversionResult#getNetAmount()}.
18 * A convertor must not convert to a different currency than the one specified in the request.
20 * When the need comes to extend the semantics, one subclasses the ConversionRequest and/or ConversionResult classes.
22 * This method can be called as many times as you like.
23 * A {@link Convertor} shall be considered immutable wrt calls to {@link #convert(org.apidesign.apifest08.currency.Convertor.ConversionRequest).
24 * This method of a single {@link Convertor} can be called from many threads concurrently.
25 * @param req the conversion request; mustn't be null
26 * @return the result of carrying out the conversion request; never null
27 * @throws IllegalRequestSubtypeException when the particular implementation cannot handle a specific ConversionRequest type
29 public ConversionResult convert( final ConversionRequest req ) throws IllegalRequestSubtypeException;
32 * The request for converting a monetary amout into another currency.
35 public class ConversionRequest {
37 private final MonetaryAmount srcAmount;
38 private final Currency tgtCurrency;
41 * A request to convert srcAmount into tgtCurrency.
42 * @param srcAmount the source amount; must not be null
43 * @param tgtCurrency the currency we want it in afterwards; must not be null
45 public ConversionRequest( final MonetaryAmount srcAmount, final Currency tgtCurrency ) {
46 this.srcAmount = srcAmount;
47 this.tgtCurrency = tgtCurrency;
48 if ( srcAmount == null ) {
49 throw new NullPointerException( "The source amount" );
51 if ( tgtCurrency == null ) {
52 throw new NullPointerException( "The target currency" );
54 if ( srcAmount.getCurrency().equals( tgtCurrency ) ) {
55 throw new IllegalArgumentException( "Cannot request conversion from " + srcAmount.getCurrency() + " to " + tgtCurrency );
62 public MonetaryAmount getSrcAmount() {
67 * The target currency.
69 public Currency getTgtCurrency() {
76 * The result of converting a monetary amount into another currency.
77 * For now it records just the net amount one recieves from the conversion.
80 * <b>Extension note:</b>
81 * Other items can be added further down the road, as the need for them arises.
82 * These items might provide info on other aspects of the conversion,
83 * such as the fee or a reason why the conversion might not be admissible.
85 public class ConversionResult {
87 private final MonetaryAmount netAmount;
90 * A new conversion result.
91 * @param netAmount the amount one recieves from the conversion;
92 * null means the conversion was not admissible
94 public ConversionResult( final MonetaryAmount netAmount ) {
95 this.netAmount = netAmount;
99 * The amount one recieves from the conversion.
100 * If null, the conversion is not admissible.
103 public MonetaryAmount getNetAmount() {