Download archive here

Euro-Conversion

Version 1.1a, 27.11.2000
Status: complete

Index

1. Introduction

2. Domain Classes

3. Currency Input Field

4. Example/Test Application

5. Changes

6. References

1. Introduction

1.1 The package magie.currency

The package magie.currency and all its sub-packages and extensions is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the

Or visit http://www.gnu.org/copyleft/lesser.html.

1.2 Requirements

The legal requirements are defined in the EC Guideline No. 1103/97, Article 4, 5 (see [2]). The most important legal requirements include:

• The conversion rates must consist of excatly 6 valid digits.
• An inverse conversion rate may not be used.
• The conversion rates may not be rounded or cut.
• In the conversion several rules are defined how results and intermediary result have been rounded.

The package uses the following EUR-Currencies and exchange rates:

1.3 Usage

The library, which consists of two core parts, can be used in the following way:

• Currency
  Instances of this class can be used to replace numbers, as Doubles, used in the domain model to model monetary values, adding support for multiple currency units, arithmetic operations and conversion into other currency units.
• CurrencyField
  This JavaBean can be used to replace JTextFields to directly edit Currency objects and to control the model and the display currency unit.

1.4 Structure

The following table provides an overview about the packages of the magie.currency library and its objectives:

1.5 Application specific solutions

Non-EUR Currencies are not provided, nor mechanisms to perform currency conversion. In order to extend the package, the abstract Currency Unit classes may be subclassed to implement this behavior.

In addition, all application systems are responsible for

• The handling of Currency Exceptions,
• The provision of a Currency Unit for a certain context, e.g. system Currency Unit, document Currency Unit etc.

2. Domain Classes

The core business functionality of the Euro converter is done within the classes of the currency domain package magie.currency. The following class diagram shows the classes of this package, the attributes and the business methods.

Figure 1: Class diagram domain classes

2.1 Currency

The class Currency, defined in the package magie.currency, is the model for monetary amounts used in the application's domain. It replaces objects of the type Double, which may be used in single currency unit application, in order to make monetary amounts dependent on their currency unit. Therefor the class Currency is composed of two attributes,

In addition, the Currency class provides and encapsulates the business behavior for the domain related to monetary values, as there are:

• arithmetic operations,
• conversion,
• parsing from Strings and displaying as Strings,
• comparison,
• rounding (to the legal scale).

2.2 CurrencyUnit

Class CurrencyUnit is used as unit for Currency objects. There are two different Currency Unit implementation available within the magie.currency package:

• CurrencyUnit
  the core implementation of the Currency Unit, which defines some default behavior. This class can be used for (non-EUR) Currencies, which shall not be converted.
• EurCurrencyUnit
  This class specialises its superclass by providing a conversion rate and scale, and overridden implementations of the conversion methods, which are used to convert Currency objects.

The implementation of these classes encapsulates the EUR currencies and its rates and scales. This is done with the private method

 /**
  * create all required instances of the currency units
  * and save them into the dictionary
  */
  private static void initializeEurUnits() {
    currencyUnits = new Hashtable();
    currencyUnits.put("ATS", new EurCurrencyUnit("ATS", 13.7603d));
    currencyUnits.put("BEF", new EurCurrencyUnit("BEF", 40.3399d));
    currencyUnits.put("DEM", new EurCurrencyUnit("DEM", 1.95583d));
    currencyUnits.put("ESP", new EurCurrencyUnit("ESP", 166.386d));
    currencyUnits.put("FIM", new EurCurrencyUnit("FIM", 5.94573d));
    currencyUnits.put("FRF", new EurCurrencyUnit("FRF", 6.55957d));
    currencyUnits.put("IEP", new EurCurrencyUnit("IEP", 0.787564d));
    currencyUnits.put("ITL", new EurCurrencyUnit("ITL", 1936.27d, 0));
    currencyUnits.put("LUF", new EurCurrencyUnit("LUF", 40.3399d));
    currencyUnits.put("NLG", new EurCurrencyUnit("NLG", 2.20371d));
    currencyUnits.put("PTE", new EurCurrencyUnit("PTE", 200.482d));
    currencyUnits.put("EUR", new EurCurrencyUnit("EUR", 1.00000d));
  }

The core methods are listed in the following table:

2.3 Currency Conversion

The Euro-Conversion is performed in a two-step-procedure

1. convert source Currency to EUR
2. convert EUR to target currency

The following method definition illustrates the implementation of this approach:

 /**
  * convert Currency aCurrency into the given CurrencyUnit
  *
  * @param  aCurrency (Currency) Currency to be converted
  * @param  newCurrencyUnit (Type) destination CurrencyUnit
  * @return (Currency) the converted Currency
  */
  public Currency convert(Currency aCurrency, CurrencyUnit newCurrencyUnit)
                        throws CurrencyConversionException {

    Currency curr = aCurrency;
    // 1. convert currency to EUR
    if(!curr.getUnit().isEUR()) {
      curr = convertedToEUR(curr);
    }
    // 2. convert EUR to target currency
    if(!newCurrencyUnit.isEUR()) {
      curr = newCurrencyUnit.convertedFromEUR(curr);
    }
    return curr;
  }

I'd like to discuss some special behavior here:

• If the source Currency is EUR, the first step is skipped.
• If the target Currency is EUR, the second step is skipped.
• If the source Currency has a Currency Unit of the type CurrencyUnit (which is not convertible), the default implementation of the above method is used and a CurrencyConversionException is thrown.
• If the target Currency has a Currency Unit of the type CurrencyUnit, the method convertedFromEUR() throws an CurrencyConversionException.
• Application specific subclasses of CurrencyUnit may define special conversion for convertible non-EUR currencies by overriding these methods.

2.4 Arithmetic Operations

The arithmetic operations of the Currency class are based on some general rules:

• Only Currency objects with the same CurrencyUnit may be added or subtracted, otherwise a CurrencyException is thrown.
• Currencies may only be multiplied with numeric values (int or double)
• Currencies may divided by numeric values or Currencies with the same CurrencyUnit.
• Divisions and multiplication operations always include rounding to the defined scale. The scale is defined with 2 digits for most Euro Currencies with the exception of Italian Lira, which are defined with 0 digits.
• All operations are performed within the precision limit of the Java double type (64 bits). The application using the library is responsible for the correct handling of precision problems (as if it would handle amounts of the type double). The Currency conversion was tested for amounts within a precision range between -99.999.999,99 EUR ... 99.999.999,99 EUR.

2.5 Rounding Differences

In the available library release the tracking of rounding differences resulting from arithmetic operations and/or conversions is not implemented. This fact is important especially for the addition of converted Currencies: Keep in mind, that the sum of converted currencies might be different from the converted sum of the currencies! The application using the library is responsible for the correct use of the classes by itself.

2.6 Exceptions

For passing error states to the applications, that uses the library, two Exception subclasses have been provided:

• CurrencyException
  used to notify about errors occurring while instantiating currencies (e.g. invalid currency unit identifier) or while performing arithmetic operations (e.g. adding currencies with different currency units),
• CurrencyConversionException
  used to notify about errors originated in one of the currency conversion methods, e.g. when currencies are converted to currencies with non-EUR currency unit.

3. Currency Input Field

The CurrencyField is a subclass of JTextField which is aimed to edit Currency instances directly. Therefor the widget references a Currency object, to which it is connected. Applications can access this Currency object with the getCurrency() and setCurrency() methods of the field.

3.1 Bean Properties

The CurrencyField is implemented as JavaBean, adding several properties to customise the field according to application requirements.

In order to define the properties at built-time, for the properties showUnit and resetInvalidEntry are supported by two Property Editors, the classes ResetInvalidEntryEditor and ShowUnitEditor, which simply subclass PropertyEditorSupport.

3.2 Model and Display Currency

Two CurrencyUnits can be passed to the CurrencyField to control its behavior with regards of conversion of currencies:

• ModelCurrency
  The Currency Unit, in which the Currency edited by the field is processed/converted.
• DisplayCurrency
  The Currency Unit, in which the Currency edited by the field is displayed. This conversion is only be done to determine the String representation to be displayed, but does not change the model itself. If Model Currency and Display Currency are different, the display color of the field changes to grey.

The Model Currency can thus be used to ensure, that inputs of monetary amounts are assigned with the right currency unit. For example, when the Model Currency of all Currency Fields is set to a system currency, all currencies in the system are processed in this currency unit. The Model Currency should be the "target" Currency Unit, e.g. the unit in which the data are stored in a database. The currency property f the Currency Field is converted to the Model Currency unit when the setModelCurrency() is called. After a focusLost() call of the Currency Field the input value is parsed, a Currency is instantiated and the result is converted to the Model Currency.

The Display Currency enables the end user of the library to display currencies in a preferred Currency Unit. For example, the user can select the Display Currency from a Choice within his application and all monetary amounts are displayed in this Currency Unit without impacting the Currency Unit, in which the data are stored or processed.

Both Currency Units may be set to null. The following table indicates, which behavior is gained with all possible use cases:

3.3 Event Handling

The CurrencyField defines its own event to notify its CUrrencyChangeListeners about changes of the edited Currency. Therefore the following methods are used:

For this event notification the interface CurrencyChangeListener, extending the EventListener interface, was introduced. It simply defines one method, the currencyChanged() method, which uses a CurrencyEvent, another extension of the class AWTEvent, as argument.

4. Example/Test Application

4.1 Automated Tests

To test the Euro-Converter library a JUnit test case was implemented. The test case can be found in the package magie.currency.testcase in the class CurrencyTestCase. This class extends the class TestCase of the JUnit testing framework. For all tests a testing method is implemented as Java code. The table shows, what is being tested. See source code for further details!

4.2 Test Application

To test the Currency Input Field bean and to demonstrate the usage of the classes the class CurrencyTestApplication in the package magie.currency.ui.test is used.

The core widget of the little test application is the CurrencyField, labelled "A Currency". This can be used to enter monetary amounts and display them. The display field labelled "The Model" provides a toString() representation of the Currency object edited by the CurrencyField. All bean properties as listed in the above can be changed by the Checkboxes and the Choices in the frame:

• show unit
  if checked the currency unit of the edited Currency is displayed
• reset display
  if checked the field is cleared after an invalid input, otherwise the display is replaced with the formatted output resulting from the previous Currency object.
• Display
  choose the Display Currency (or null)
• Model
  choose the Model Currency (or null)

Figure 2: Currency Test Application

The frame itself is implemented as CurrencyChangeListener in order to be notified on Currency change. Here the currencyChanged() method displays the edited Currency in the display field.

The CurrencyField's handleException() method is overridden by an anonymous inner class, which simply outputs Exceptions, which are thrown by the Currency class to the CurrencyField (and usually caught and handled by the widget). With this mechanisms application specific behavior can be added to the bean, e.g. to notify the user about an invalid entry, using the application specific message handling mechanisms.

5. Changes:

6. References

[R1] GNU Lesser General Public License

[R2] Verordnung (EG) Nr. 1103/97 des Rates vom 17. Juni über bestimmte Vorschriften im Zusammenhang mit der Einführung des Euro

[R3] JUnit Documentation http://www.armaties.com/extreme.htm

[R4] Download Sources here.