Class Money

java.lang.Object
  |
  +--Money

All Implemented Interfaces:

Cloneable, Serializable

public class Money

extends Object

implements Cloneable, Serializable

Class Money

The Money class represents a United States monetary value, expressed in dollars and cents. Internally, the value is represented using Java's BigDecimal class.

Methods are provided to perform all the usual arithmetic manipulations required when dealing with monetary data, including add, subtract, multiply, and divide.

Rounding

Rounding does not occur during intermediate computations; maximum precision (and accuracy) is thus preserved throughout all computations. Round-off to an integral cent occurs only when the monetary value is externalized (when formatted for display as a String or converted to a long integer). One of several different rounding modes can be specified. The default rounding mode is to discard any fractional cent and truncate the monetary value to 2 decimal places.

Currency Format

A Currency Format (an instance of DecimalFormat) is used to control formatting of monetary values for display as well as the parsing of strings which represent monetary values. By default, the Currency Format for the current locale is used. For the United States, the default Currency Symbol is the Dollar Sign ("$"). Negative amounts are enclosed in parentheses. A Decimal Point (".") separates the dollars and cents, and a comma (",") separates each group of 3 consecutive digits in the dollar amount.

Examples: $1,234.56 ($1,234.56)

Immutability

Money objects, like String objects, are immutable. An operation on a Money object (such as add, subtract, etc.) does not alter the object in any way. Rather, a new Money object is returned whose state reflects the result of the operation. Thus, a statement like

money1.add(money2);

has no effect; it does not modify money1 in any way, and the result is effectively discarded. If the intent is to modify money1, then you should code

money1 = money1.add(money2);

which effectively replaces money1 with the result.

See Also:

BigDecimal, DecimalFormat, Serialized Form

Inner Class Summary

static class	Money.InvalidRoundingModeException Class InvalidRoundingModeException
static class	Money.InvalidScaleFactorException Class InvalidScaleFactorException

Field Summary

protected DecimalFormat	currencyFormat The Currency Format, used for formatting and parsing a monetary value.
protected int	roundingMode The Rounding Mode.
protected BigDecimal	value The monetary value.
protected static BigDecimal	ZERO The special monetary value of zero ($0.00).

Constructor Summary

Money()
Default Constructor for a Money object; creates an object whose value is $0.00.

Money(BigDecimal amount)
Constructs a Money object from a BigDecimal object.

Money(double amount)
Constructs a Money object from a double-precision, floating-point value.

Money(long amount)
Constructs a Money object from a long integer value.

Money(long amount, int scale)
Constructs a Money object from a long integer value with a specified scale factor.

Money(Money amount)
Copy Constructor; constructs a Money object from another Money object.

Money(String string)
Constructs a Money object from a string representation of a monetary value.

Method Summary

Money	abs() Returns the absolute monetary value.
Money	add(Money money) Adds a specified monetary value to this monetary value.
Object	clone() Clones a Money object.
Money	divide(double div) Divides this monetary value by a specified value.
Money	divide(long div) Divides this monetary value by a specified value.
boolean	equals(Object object) Compares this object with the specified object.
DecimalFormat	getCurrencyFormat() Returns the Currency Format, used to format and parse monetary values.
int	getRoundingMode() Returns the Rounding Mode.
BigDecimal	getValue() Returns the monetary value as a BigDecimal object.
int	hashCode() Returns a hashcode for this object.
boolean	isEqual(Money other) Returns an indication of whether or not this monetary value is equal to another monetary value.
boolean	isGreaterThan(Money other) Returns an indication of whether or not this monetary value is greater than another monetary value.
boolean	isGreaterThanOrEqual(Money other) Returns an indication of whether or not this monetary value is greater than or equal to another monetary value.
boolean	isLessThan(Money other) Returns an indication of whether or not this monetary value is less than another monetary value.
boolean	isLessThanOrEqual(Money other) Returns an indication of whether or not this monetary value is less than or equal to another monetary value.
boolean	isNegative() Returns an indication of whether or not this monetary value is negative (less than $0.00).
boolean	isPositive() Returns an indication of whether or not this monetary value is positive (greater than or equal to $0.00).
boolean	isZero() Returns an indication of whether or not this monetary value is zero (equal to $0.00).
Money	multiply(double mult) Multiplies this monetary value by a specified value.
Money	multiply(long mult) Multiplies this monetary value by a specified value.
Money	negate() Negates this monetary value.
Money	parse(String string) Parses a string representation of a monetary value, returning a new Money object with the specified value.
Money	setCurrencyFormat(DecimalFormat format) Sets the Currency Format, used for formatting and parsing monetary values.
Money	setRoundingMode(int mode) Sets the Rounding Mode.
Money	subtract(Money money) Subtracts a specified monetary value from this monetary value.
double	toDouble() Returns the monetary value as a double-precision, floating-point value.
long	toLong() Returns the monetary value as a long integer with 2 decimal digits to the right of an implicit decimal point.
String	toString() Returns a formatted string representation of the monetary value.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

value

protected BigDecimal value

The monetary value.

roundingMode

protected int roundingMode

The Rounding Mode. Specifies if and how the monetary value is to be rounded off to an integral cent.

currencyFormat

protected DecimalFormat currencyFormat

The Currency Format, used for formatting and parsing a monetary value. Refer to the Java API documentation for the DecimalFormat class for information on formats.

ZERO

protected static final BigDecimal ZERO

The special monetary value of zero ($0.00).

Constructor Detail

Money

public Money()

Default Constructor for a Money object; creates an object whose value is $0.00.

Money

public Money(double amount)

Constructs a Money object from a double-precision, floating-point value. The Currency Format is set to the default format for the current locale.

The integral part of the value represents whole dollars, and the fractional part of the value represents fractional dollars (cents). As an example, the value 19.95 would represent $19.95.

Parameters:

amount - The monetary amount, in dollars and cents

Money

public Money(long amount)

Constructs a Money object from a long integer value. The specified value represents whole dollars only (that is, cents are implicity assumed to be 00). For example, the integer 25 would represent a monetary value of $25.00.

Parameters:

amount - The monetary amount, in whole dollars (no cents)

Money

public Money(long amount,
             int scale)
      throws Money.InvalidScaleFactorException

Constructs a Money object from a long integer value with a specified scale factor. The scale factor (0, 1, or 2) specifies the number of digits to the right of an implied decimal point.

For example, the value 1995 would be interpreted as a monetary value of $1995.00, $199.50, and $19.95 for scale factors of 0, 1, or 2, respectively.

Parameters:

amount - The monetary amount, in dollars and cents

scale - Scale factor (must be 0, 1, or 2)

Throws:

Money.InvalidScaleFactorException - The scale factor specified is not valid (must be 0, 1, or 2)

Money

public Money(String string)
      throws ParseException

Constructs a Money object from a string representation of a monetary value. The format of the string must be consistent with the Currency Format; otherwise, a ParseException is recognized. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.

Parameters:

string - A String representing a monetary value

Throws:

ParseException - The string is inconsistent with the Currency Format

See Also:

DecimalFormat, setCurrencyFormat(java.text.DecimalFormat)

Money

public Money(BigDecimal amount)

Constructs a Money object from a BigDecimal object.

Parameters:

amount - A BigDecimal value representing a monetary amount, in dollars and cents

Money

public Money(Money amount)

Copy Constructor; constructs a Money object from another Money object.

Parameters:

amount - A Money object

Method Detail

add

public Money add(Money money)

Adds a specified monetary value to this monetary value.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

money - The monetary value to be added

Returns:

A new Money object representing the result

subtract

public Money subtract(Money money)

Subtracts a specified monetary value from this monetary value.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

money - The monetary value to be subtracted

Returns:

A new Money object representing the result

multiply

public Money multiply(double mult)

Multiplies this monetary value by a specified value.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

mult - The multiplier value

Returns:

A new Money object representing the result

multiply

public Money multiply(long mult)

Multiplies this monetary value by a specified value.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

mult - The multiplier value

Returns:

A new Money object representing the result

divide

public Money divide(double div)

Divides this monetary value by a specified value.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

div - The divisor value

Returns:

A new Money object representing the result

divide

public Money divide(long div)

Divides this monetary value by a specified value.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

div - The divisor value

Returns:

A new Money object representing the result

negate

public Money negate()

Negates this monetary value. Positive values become negative, and negative values become positive. The effect is the same as if the monetary value were multiplied by -1.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Returns:

A new Money object representing the result

abs

public Money abs()

Returns the absolute monetary value. A positive value is returned, irrespective of whether the monetary value is positive or negative.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Returns:

A new Money object representing the result

toLong

public long toLong()

Returns the monetary value as a long integer with 2 decimal digits to the right of an implicit decimal point. For example, if the monetary value were $19.95, a value of 1995 would be returned. Note that the monetary value is rounded, if necessary, according to the specified Rounding Mode.

Returns:

The monetary value

toDouble

public double toDouble()

Returns the monetary value as a double-precision, floating-point value.

Note: Exercise care when converting monetary values to floating point values, because floating-point arithmetic is not well-suited for use with monetary data.

Returns:

The monetary value

getValue

public BigDecimal getValue()

Returns the monetary value as a BigDecimal object.

Returns:

The monetary value

getRoundingMode

public int getRoundingMode()

Returns the Rounding Mode. Refer to Java's BigDecimal object for a description of the possible rounding modes.

Returns:

The Rounding Mode

See Also:

BigDecimal.ROUND_UP, BigDecimal.ROUND_DOWN, BigDecimal.ROUND_CEILING, BigDecimal.ROUND_FLOOR, BigDecimal.ROUND_HALF_UP, BigDecimal.ROUND_HALF_DOWN, BigDecimal.ROUND_HALF_EVEN

setRoundingMode

public Money setRoundingMode(int mode)
                      throws Money.InvalidRoundingModeException

Sets the Rounding Mode. Refer to the Java API documentation for the BigDecimal class for a description of the possible Rounding Modes. The default Rounding Mode is BigDecimal.ROUND_DOWN, which effectively discards any fractional cent amount and truncates the monetary value to 2 decimal places. A Rounding Mode of BigDecimal.ROUND_UNNECESSARY is not valid for use with monetary data since certain operations result in a loss of precision and therefore require that a rounding mode be explicitly specified.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

int - The Rounding Mode

Returns:

A new Money object representing the result

Throws:

Money.InvalidRoundingModeException - The Rounding Mode specified is not valid for monetary data

See Also:

BigDecimal.ROUND_UP, BigDecimal.ROUND_DOWN, BigDecimal.ROUND_CEILING, BigDecimal.ROUND_FLOOR, BigDecimal.ROUND_HALF_UP, BigDecimal.ROUND_HALF_DOWN, BigDecimal.ROUND_HALF_EVEN

getCurrencyFormat

public DecimalFormat getCurrencyFormat()

Returns the Currency Format, used to format and parse monetary values. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.

Returns:

The Currency Format

See Also:

DecimalFormat

setCurrencyFormat

public Money setCurrencyFormat(DecimalFormat format)

Sets the Currency Format, used for formatting and parsing monetary values. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.

By default, the Currency Format for the current locale is used. For the United States, the default Currency Symbol is the Dollar Sign ("$"). Negative amounts are enclosed in parentheses. A Decimal Point (".") separates the dollars and cents, and a comma (",") separates each group of 3 consecutive digits in the dollar amount.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

format - The Currency Format

Returns:

A new Money object representing the result

See Also:

DecimalFormat

toString

public String toString()

Returns a formatted string representation of the monetary value. The format of the string is determined by the Currency Format. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.

By default, the Currency Format for the current locale is used.

Overrides:

toString in class Object

Returns:

A string representation of the monetary value

See Also:

DecimalFormat, setCurrencyFormat(java.text.DecimalFormat)

parse

public Money parse(String string)
            throws ParseException

Parses a string representation of a monetary value, returning a new Money object with the specified value. The format of the string must be consistent with the Currency Format; otherwise, a ParseException is recognized. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.

The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.

Parameters:

string - A String representing a monetary value

Returns:

A new Money object representating the parsed monetary value

Throws:

ParseException - The string is inconsistent with the Currency Format

See Also:

DecimalFormat, setCurrencyFormat(java.text.DecimalFormat)

isZero

public boolean isZero()

Returns an indication of whether or not this monetary value is zero (equal to $0.00).

Returns:

true The monetary value is zero
false The monetary value is not zero

isNegative

public boolean isNegative()

Returns an indication of whether or not this monetary value is negative (less than $0.00).

Returns:

true The monetary value is negative
false The monetary value is not negative

isPositive

public boolean isPositive()

Returns an indication of whether or not this monetary value is positive (greater than or equal to $0.00).

Returns:

true The monetary value is positive
false The monetary value is not positive

isEqual

public boolean isEqual(Money other)

Returns an indication of whether or not this monetary value is equal to another monetary value.

Parameters:

other - A monetary value with which this monetary value is to be compared

Returns:

true This monetary values are equal
false This monetary values are not equal

isLessThan

public boolean isLessThan(Money other)

Returns an indication of whether or not this monetary value is less than another monetary value.

Parameters:

other - A monetary value with which this monetary value is to be compared

Returns:

true This monetary value is less than the specified monetary value
false This monetary value is not less than the specified monetary value

isLessThanOrEqual

public boolean isLessThanOrEqual(Money other)

Returns an indication of whether or not this monetary value is less than or equal to another monetary value.

Parameters:

other - A monetary value with which this monetary value is to be compared

Returns:

true This monetary value is less than or equal to the specified monetary value
false This monetary value is not less than or equal to the specified monetary value

isGreaterThan

public boolean isGreaterThan(Money other)

Returns an indication of whether or not this monetary value is greater than another monetary value.

Parameters:

other - A monetary value with which this monetary value is to be compared

Returns:

true This monetary value is greater than the specified monetary value
false This monetary value is not greater than the specified monetary value

isGreaterThanOrEqual

public boolean isGreaterThanOrEqual(Money other)

Returns an indication of whether or not this monetary value is greater than or equal to another monetary value.

Parameters:

other - A monetary value with which this monetary value is to be compared

Returns:

true This monetary value is greater than or equal to the specified monetary value
false This monetary value is not greater than or equal to the specified monetary value

equals

public boolean equals(Object object)

Compares this object with the specified object. The objects are equal if and only if the specified object is not null, is a Money object, and has the same monetary value as this object.

Overrides:

equals in class Object

Parameters:

object - Some object

Returns:

true The objects are equal
false The objects are not equal

hashCode

public int hashCode()

Returns a hashcode for this object. The hashcode is identical to that for the BigDecimal object that represents the monetary value.

Overrides:

hashCode in class Object

Returns:

The hashcode

clone

public Object clone()

Clones a Money object. The new object is an exact copy of this object, and inherits the object's monetary value and Currency Format.

Overrides:

clone in class Object

Returns:

Money The cloned object