title: "Money Pattern in Java: Encapsulating Monetary Values with Currency Consistency"

shortTitle: Money

description: "Learn how the Money design pattern in Java ensures currency safety, precision handling, and maintainable financial operations. Explore examples, applicability, and benefits of the pattern."

category: Behavioral

language: en

tag:

- Encapsulation

- Precision handling

- Currency safety

- Value Object

- Financial operations

- Currency

- Financial

- Immutable

- Value Object

* Monetary Value Object

The Money design pattern provides a robust way to encapsulate monetary values and their associated currencies. It ensures precise calculations, currency consistency, and maintainability of financial logic in Java applications.

In this example:

- Each monetary value (like a product price or tax amount) is encapsulated in a `Money` object.

- The `Money` class ensures that only values in the same currency are combined and supports safe currency conversion for global operations.

public class Money {

private @Getter double amount;

private @Getter String currency;

public Money(double amnt, String curr) {

this.amount = amnt;

this.currency = curr;

}

private double roundToTwoDecimals(double value) {

return Math.round(value * 100.0) / 100.0;

}

public void addMoney(Money moneyToBeAdded) throws CannotAddTwoCurrienciesException {

if (!moneyToBeAdded.getCurrency().equals(this.currency)) {

throw new CannotAddTwoCurrienciesException("You are trying to add two different currencies");

}

this.amount = roundToTwoDecimals(this.amount + moneyToBeAdded.getAmount());

}

public void subtractMoney(Money moneyToBeSubtracted) throws CannotSubtractException {

if (!moneyToBeSubtracted.getCurrency().equals(this.currency)) {

throw new CannotSubtractException("You are trying to subtract two different currencies");

} else if (moneyToBeSubtracted.getAmount() > this.amount) {

throw new CannotSubtractException("The amount you are trying to subtract is larger than the amount you have");

}

this.amount = roundToTwoDecimals(this.amount - moneyToBeSubtracted.getAmount());

}

public void multiply(int factor) {

if (factor < 0) {

throw new IllegalArgumentException("Factor must be non-negative");

}

this.amount = roundToTwoDecimals(this.amount * factor);

}

public void exchangeCurrency(String currencyToChangeTo, double exchangeRate) {

if (exchangeRate < 0) {

throw new IllegalArgumentException("Exchange rate must be non-negative");

}

this.amount = roundToTwoDecimals(this.amount * exchangeRate);

this.currency = currencyToChangeTo;

}

}

## When to Use the Money Pattern

The Money pattern should be used in scenarios where:

1. **Currency-safe arithmetic operations**

To ensure that arithmetic operations like addition, subtraction, and multiplication are performed only between amounts in the same currency, preventing inconsistencies or errors in calculations.

2. **Accurate rounding for financial calculations**

Precise rounding to two decimal places is critical to maintain accuracy and consistency in financial systems.

3. **Consistent currency conversion**

When handling international transactions or displaying monetary values in different currencies, the Money pattern facilitates easy and reliable conversion using exchange rates.

4. **Encapsulation of monetary logic**

By encapsulating all monetary operations within a dedicated class, the Money pattern improves maintainability and reduces the likelihood of errors.

5. **Preventing errors in financial operations**

Strict validation ensures that operations like subtraction or multiplication are only performed when conditions are met, safeguarding against misuse or logical errors.

6. **Handling diverse scenarios in financial systems**

Useful in complex systems like e-commerce, banking, and payroll applications where precise and consistent monetary value handling is crucial.

## Benefits and Trade-offs of Money Pattern

### Benefits

1. **Precision and Accuracy**

The Money pattern ensures precise handling of monetary values, reducing the risk of rounding errors.

2. **Encapsulation of Business Logic**

By encapsulating monetary operations, the pattern enhances maintainability and reduces redundancy in financial systems.

3. **Currency Safety**

It ensures operations are performed only between amounts of the same currency, avoiding logical errors.

4. **Improved Readability**

By abstracting monetary logic into a dedicated class, the code becomes easier to read and maintain.

5. **Ease of Extension**

Adding new operations, handling different currencies, or incorporating additional business rules is straightforward.

### Trade-offs

1. **Increased Complexity**

Introducing a dedicated `Money` class can add some overhead, especially for small or simple projects.

2. **Potential for Misuse**

Without proper validation and handling, incorrect usage of the Money pattern may introduce subtle bugs.

3. **Performance Overhead**

Precision and encapsulation might slightly affect performance in systems with extremely high transaction volumes.

---

## Related Design Patterns

1. **Value Object**

Money is a classic example of the Value Object pattern, where objects are immutable and define equality based on their value.

Link:https://martinfowler.com/bliki/ValueObject.html

2. **Factory Method**

Factories can be employed to handle creation logic, such as applying default exchange rates or rounding rules.

Link:https://www.geeksforgeeks.org/factory-method-for-designing-pattern/

---

## References and Credits

- [Patterns of Enterprise Application Architecture](https://martinfowler.com/eaaCatalog/money.html) by Martin Fowler

- [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3w0pvKI)

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>

<parent>

<groupId>com.iluwatar</groupId>

<artifactId>java-design-patterns</artifactId>

<version>1.26.0-SNAPSHOT</version>

</parent>

<artifactId>money</artifactId>

<dependencies>

<dependency>

<groupId>org.junit.jupiter</groupId>

<artifactId>junit-jupiter-api</artifactId>

<scope>test</scope>

</dependency>

</dependencies>

</project>

package com.iluwatar;

import java.util.logging.Level;

import java.util.logging.Logger;

public class App {

// Initialize the logger

private static final Logger logger = Logger.getLogger(App.class.getName());

/**

public static void main(String[] args) {

// Create instances of Money

Money usdAmount1 = new Money(50.00, "USD");

Money usdAmount2 = new Money(20.00, "USD");

// Demonstrate addition

try {

usdAmount1.addMoney(usdAmount2);

logger.log(Level.INFO, "Sum in USD: {0}", usdAmount1.getAmount());

} catch (CannotAddTwoCurrienciesException e) {

logger.log(Level.SEVERE, "Error adding money: {0}", e.getMessage());

}

// Demonstrate subtraction

try {

usdAmount1.subtractMoney(usdAmount2);

logger.log(Level.INFO, "Difference in USD: {0}", usdAmount1.getAmount());

} catch (CannotSubtractException e) {

logger.log(Level.SEVERE, "Error subtracting money: {0}", e.getMessage());

}

// Demonstrate multiplication

try {

usdAmount1.multiply(2);

logger.log(Level.INFO, "Multiplied Amount in USD: {0}", usdAmount1.getAmount());

} catch (IllegalArgumentException e) {

logger.log(Level.SEVERE, "Error multiplying money: {0}", e.getMessage());

}

// Demonstrate currency conversion

try {

double exchangeRateUsdToEur = 0.85; // Example exchange rate

usdAmount1.exchangeCurrency("EUR", exchangeRateUsdToEur);

logger.log(Level.INFO, "USD converted to EUR: {0} {1}", new Object[]{usdAmount1.getAmount(), usdAmount1.getCurrency()});

} catch (IllegalArgumentException e) {

logger.log(Level.SEVERE, "Error converting currency: {0}", e.getMessage());

}

}

}

package com.iluwatar;

public class CannotAddTwoCurrienciesException extends Exception {

/**

public CannotAddTwoCurrienciesException(String message) {

super(message);

}

}

package com.iluwatar;

public class CannotSubtractException extends Exception {

/**

public CannotSubtractException(String message) {

super(message);

}

}