User guide

Joda-Money is a small Java library providing classes to store, format and parse amounts of money. This is a brief user guide to the features available.

Main classes

There are two main classes which are both based on BigDecimal:

  • Money - an amount in a single currency where the decimal places is determined by the currency
  • BigMoney - an amount in a single currency where there is no restriction on the scale

For example, the currencies of US dollars, Euros and British Pounds all use 2 decimal places, thus a Money instance for any of these currencies will have 2 decimal places. By contrast, the Japanese Yen has 0 decimal places, and thus any Money instance with that currency will have 0 decimal places.

Instances of BigMoney may have any scale that can be supported by BigDecimal.

Conversion between a Money and a BigMoney can be performed using the methods toBigMoney() and toMoney(). The latter optionally takes a rounding mode to handle the case where information must be lost.

Both classes implement the BigMoneyProvider interface. This allows many different classes, including user supplied classes, to interoperate with Joda-Money. A common pattern when writing flexible methods for handling money is to accept this interface. The formatting code is a good example of this.

Currency information

Joda-Money includes its own currency class as the implementation in the JDK is too restrictive. The data for the Joda-Money class is provided by two configuration files.

The file org/joda/money/MoneyData.csv holds a basic list of valid currencies. The columns are as follows:

  • ISO-4217 currency code - three letters, mandatory
  • ISO-4217 numeric code - from 1 to 999, set to -1 if no numeric code
  • Number of decimal places in common usage - the supplied data is based on various sources
  • Country codes - a list of ISO-3166-1country codes, adjacent to one another and without separators

The library will load the first version of this file it finds in the classpath based on the class loader that Joda-Money is loaded in.

The file org/joda/money/MoneyDataExtension.csv holds any user extensions to the currency list. It has the same file format as above. This file is optional and not supplied by default. Again, the first instance of the file on the classpath will be loaded.

Formatting

Formatting is based around the MoneyFormatterBuilder class. The builder is used to create a suitable format which is then converted to an immutable MoneyFormatter instance. The format may contain localized aspects which can be use by calling withLocale() on the formatter. This returns a new formatter as it is immutable.

The symbol information for formatting is currently provided by the JDK.