docs: update domain model

Author: iluwatar

domain-model/README.md

@@ -1,14 +1,20 @@
 ---
 title: Domain Model
-category: Architectural
+category: Structural
 language: en
 tag:
- - Domain
+    - Business
+    - Domain
 ---
 
+## Also known as
+
+* Conceptual Model
+* Domain Object Model
+
 ## Intent
 
-Domain model pattern provides an object-oriented way of dealing with complicated logic. Instead of having one procedure that handles all business logic for a user action there are multiple objects and each of them handles a slice of domain logic that is relevant to it.
+The Domain Model pattern aims to create a conceptual model in your software that matches the real-world system it's designed to represent. It involves using rich domain objects that encapsulate both data and behavior relevant to the application domain.
 
 ## Explanation
 
@@ -24,300 +30,121 @@ Programmatic Example
 
 In the example of the e-commerce app, we need to deal with the domain logic of customers who want to buy products and return them if they want. We can use the domain model pattern and create classes `Customer` and `Product` where every single instance of that class incorporates both behavior and data and represents only one record in the underlying table.
 
-Here is the `Product` domain class with fields `name`, `price`, `expirationDate` which is specific for each product, `productDao` for working with DB, `save` method for saving product and `getSalePrice` method which return price for this product with discount.
-
 ```java
-@Slf4j
-@Getter
-@Setter
-@Builder
-@AllArgsConstructor
-public class Product {
-
-    private static final int DAYS_UNTIL_EXPIRATION_WHEN_DISCOUNT_ACTIVE = 4;
-    private static final double DISCOUNT_RATE = 0.2;
-
-    @NonNull private final ProductDao productDao;
-    @NonNull private String name;
-    @NonNull private Money price;
-    @NonNull private LocalDate expirationDate;
-
-    /**
-     * Save product or update if product already exist.
-     */
-    public void save() {
-        try {
-            Optional<Product> product = productDao.findByName(name);
-            if (product.isPresent()) {
-                productDao.update(this);
-            } else {
-                productDao.save(this);
-            }
-        } catch (SQLException ex) {
-            LOGGER.error(ex.getMessage());
-        }
-    }
+public class Customer {
+    // Customer properties and methods
+}
 
-    /**
-     * Calculate sale price of product with discount.
-     */
-    public Money getSalePrice() {
-        return price.minus(calculateDiscount());
-    }
+public class Product {
+    // Product properties and methods
+}
+```
 
-    private Money calculateDiscount() {
-        if (ChronoUnit.DAYS.between(LocalDate.now(), expirationDate)
-                < DAYS_UNTIL_EXPIRATION_WHEN_DISCOUNT_ACTIVE) {
+Data Access Objects (DAOs): These objects provide an abstract interface to the database. They are used to retrieve domain entities and save changes back to the database. In the provided code, CustomerDaoImpl and ProductDaoImpl are the DAOs.
 
-            return price.multipliedBy(DISCOUNT_RATE, RoundingMode.DOWN);
-        }
+```java
+public class CustomerDaoImpl implements CustomerDao {
+    // Implementation of the methods defined in the CustomerDao interface
+}
 
-        return Money.zero(USD);
-    }
+public class ProductDaoImpl implements ProductDao {
+    // Implementation of the methods defined in the ProductDao interface
 }
 ```
 
-Here is the `Customer` domain class with fields `name`, `money` which is specific for each customer, `customerDao` for working with DB, `save` for saving customer, `buyProduct` which add a product to purchases and withdraw money, `returnProduct` which remove product from purchases and return money, `showPurchases` and `showBalance` methods for printing customer's purchases and money balance.
+Domain Logic: This is encapsulated within the domain entities. For example, the Customer class has methods like buyProduct() and returnProduct() which represent the actions a customer can perform.
 
 ```java
-@Slf4j
-@Getter
-@Setter
-@Builder
 public class Customer {
+    // ...
 
-    @NonNull private final CustomerDao customerDao;
-    @Builder.Default private List<Product> purchases = new ArrayList<>();
-    @NonNull private String name;
-    @NonNull private Money money;
-
-    /**
-     * Save customer or update if customer already exist.
-     */
-    public void save() {
-        try {
-            Optional<Customer> customer = customerDao.findByName(name);
-            if (customer.isPresent()) {
-                customerDao.update(this);
-            } else {
-                customerDao.save(this);
-            }
-        } catch (SQLException ex) {
-            LOGGER.error(ex.getMessage());
-        }
-    }
-
-    /**
-     * Add product to purchases, save to db and withdraw money.
-     *
-     * @param product to buy.
-     */
     public void buyProduct(Product product) {
-        LOGGER.info(
-                String.format(
-                        "%s want to buy %s($%.2f)...",
-                        name, product.getName(), product.getSalePrice().getAmount()));
-        try {
-            withdraw(product.getSalePrice());
-        } catch (IllegalArgumentException ex) {
-            LOGGER.error(ex.getMessage());
-            return;
-        }
-        try {
-            customerDao.addProduct(product, this);
-            purchases.add(product);
-            LOGGER.info(String.format("%s bought %s!", name, product.getName()));
-        } catch (SQLException exception) {
-            receiveMoney(product.getSalePrice());
-            LOGGER.error(exception.getMessage());
-        }
+        // Implementation of buying a product
     }
 
-    /**
-     * Remove product from purchases, delete from db and return money.
-     *
-     * @param product to return.
-     */
     public void returnProduct(Product product) {
-        LOGGER.info(
-                String.format(
-                        "%s want to return %s($%.2f)...",
-                        name, product.getName(), product.getSalePrice().getAmount()));
-        if (purchases.contains(product)) {
-            try {
-                customerDao.deleteProduct(product, this);
-                purchases.remove(product);
-                receiveMoney(product.getSalePrice());
-                LOGGER.info(String.format("%s returned %s!", name, product.getName()));
-            } catch (SQLException ex) {
-                LOGGER.error(ex.getMessage());
-            }
-        } else {
-            LOGGER.error(String.format("%s didn't buy %s...", name, product.getName()));
-        }
-    }
-
-    /**
-     * Print customer's purchases.
-     */
-    public void showPurchases() {
-        Optional<String> purchasesToShow =
-                purchases.stream()
-                        .map(p -> p.getName() + " - $" + p.getSalePrice().getAmount())
-                        .reduce((p1, p2) -> p1 + ", " + p2);
-
-        if (purchasesToShow.isPresent()) {
-            LOGGER.info(name + " bought: " + purchasesToShow.get());
-        } else {
-            LOGGER.info(name + " didn't bought anything");
-        }
-    }
-
-    /**
-     * Print customer's money balance.
-     */
-    public void showBalance() {
-        LOGGER.info(name + " balance: " + money);
-    }
-
-    private void withdraw(Money amount) throws IllegalArgumentException {
-        if (money.compareTo(amount) < 0) {
-            throw new IllegalArgumentException("Not enough money!");
-        }
-        money = money.minus(amount);
-    }
-
-    private void receiveMoney(Money amount) {
-        money = money.plus(amount);
+        // Implementation of returning a product
     }
 }
 ```
 
-In the class `App`, we create a new instance of class Customer which represents customer Tom and handle data and actions of that customer and creating three products that Tom wants to buy.
-
+Application: The App class uses the domain entities and their methods to implement the business logic of the application.
 
 ```java
-// Create data source and create the customers, products and purchases tables
-final var dataSource = createDataSource();
-deleteSchema(dataSource);
-createSchema(dataSource);
-
-// create customer
-var customerDao = new CustomerDaoImpl(dataSource);
-
-var tom =
-    Customer.builder()
-        .name("Tom")
-        .money(Money.of(USD, 30))
-        .customerDao(customerDao)
-        .build();
-
-tom.save();
-
-// create products
-var productDao = new ProductDaoImpl(dataSource);
-
-var eggs =
-    Product.builder()
-        .name("Eggs")
-        .price(Money.of(USD, 10.0))
-        .expirationDate(LocalDate.now().plusDays(7))
-        .productDao(productDao)
-        .build();
-
-var butter =
-    Product.builder()
-        .name("Butter")
-        .price(Money.of(USD, 20.00))
-        .expirationDate(LocalDate.now().plusDays(9))
-        .productDao(productDao)
-        .build();
-
-var cheese =
-    Product.builder()
-        .name("Cheese")
-        .price(Money.of(USD, 25.0))
-        .expirationDate(LocalDate.now().plusDays(2))
-        .productDao(productDao)
-        .build();
-
-eggs.save();
-butter.save();
-cheese.save();
-
-// show money balance of customer after each purchase
-tom.showBalance();
-tom.showPurchases();
-
-// buy eggs
-tom.buyProduct(eggs);
-tom.showBalance();
-
-// buy butter
-tom.buyProduct(butter);
-tom.showBalance();
-
-// trying to buy cheese, but receive a refusal
-// because he didn't have enough money
-tom.buyProduct(cheese);
-tom.showBalance();
-
-// return butter and get money back
-tom.returnProduct(butter);
-tom.showBalance();
-
-// Tom can buy cheese now because he has enough money
-// and there is a discount on cheese because it expires in 2 days
-tom.buyProduct(cheese);
-
-tom.save();
-
-// show money balance and purchases after shopping
-tom.showBalance();
-tom.showPurchases();
+public class App {
+    public static void main(String[] args) {
+        // Create customer and products
+        // Perform actions like buying and returning products
+    }
+}
 ```
 
 The program output:
 
 ```java
-17:52:28.690 [main] INFO com.iluwatar.domainmodel.Customer - Tom balance: USD 30.00
-17:52:28.695 [main] INFO com.iluwatar.domainmodel.Customer - Tom didn't bought anything
-17:52:28.699 [main] INFO com.iluwatar.domainmodel.Customer - Tom want to buy Eggs($10.00)...
-17:52:28.705 [main] INFO com.iluwatar.domainmodel.Customer - Tom bought Eggs!
-17:52:28.705 [main] INFO com.iluwatar.domainmodel.Customer - Tom balance: USD 20.00
-17:52:28.705 [main] INFO com.iluwatar.domainmodel.Customer - Tom want to buy Butter($20.00)...
-17:52:28.712 [main] INFO com.iluwatar.domainmodel.Customer - Tom bought Butter!
-17:52:28.712 [main] INFO com.iluwatar.domainmodel.Customer - Tom balance: USD 0.00
-17:52:28.712 [main] INFO com.iluwatar.domainmodel.Customer - Tom want to buy Cheese($20.00)...
-17:52:28.712 [main] ERROR com.iluwatar.domainmodel.Customer - Not enough money!
-17:52:28.712 [main] INFO com.iluwatar.domainmodel.Customer - Tom balance: USD 0.00
-17:52:28.712 [main] INFO com.iluwatar.domainmodel.Customer - Tom want to return Butter($20.00)...
-17:52:28.721 [main] INFO com.iluwatar.domainmodel.Customer - Tom returned Butter!
-17:52:28.721 [main] INFO com.iluwatar.domainmodel.Customer - Tom balance: USD 20.00
-17:52:28.721 [main] INFO com.iluwatar.domainmodel.Customer - Tom want to buy Cheese($20.00)...
-17:52:28.726 [main] INFO com.iluwatar.domainmodel.Customer - Tom bought Cheese!
-17:52:28.737 [main] INFO com.iluwatar.domainmodel.Customer - Tom balance: USD 0.00
-17:52:28.738 [main] INFO com.iluwatar.domainmodel.Customer - Tom bought: Eggs - $10.00, Cheese - $20.00
+17:52:28.690[main]INFO com.iluwatar.domainmodel.Customer-Tom balance:USD30.00 
+17:52:28.695[main]INFO com.iluwatar.domainmodel.Customer-Tom didn't bought anything
+17:52:28.699[main]INFO com.iluwatar.domainmodel.Customer-Tom want to buy Eggs($10.00)...
+17:52:28.705[main]INFO com.iluwatar.domainmodel.Customer-Tom bought Eggs!
+17:52:28.705[main]INFO com.iluwatar.domainmodel.Customer-Tom balance:USD20.00
+17:52:28.705[main]INFO com.iluwatar.domainmodel.Customer-Tom want to buy Butter($20.00)...
+17:52:28.712[main]INFO com.iluwatar.domainmodel.Customer-Tom bought Butter!
+17:52:28.712[main]INFO com.iluwatar.domainmodel.Customer-Tom balance:USD0.00
+17:52:28.712[main]INFO com.iluwatar.domainmodel.Customer-Tom want to buy Cheese($20.00)...
+17:52:28.712[main]ERROR com.iluwatar.domainmodel.Customer-Not enough money!
+17:52:28.712[main]INFO com.iluwatar.domainmodel.Customer-Tom balance:USD0.00
+17:52:28.712[main]INFO com.iluwatar.domainmodel.Customer-Tom want to return Butter($20.00)...
+17:52:28.721[main]INFO com.iluwatar.domainmodel.Customer-Tom returned Butter!
+17:52:28.721[main]INFO com.iluwatar.domainmodel.Customer-Tom balance:USD20.00
+17:52:28.721[main]INFO com.iluwatar.domainmodel.Customer-Tom want to buy Cheese($20.00)...
+17:52:28.726[main]INFO com.iluwatar.domainmodel.Customer-Tom bought Cheese!
+17:52:28.737[main]INFO com.iluwatar.domainmodel.Customer-Tom balance:USD0.00
+17:52:28.738[main]INFO com.iluwatar.domainmodel.Customer-Tom bought:Eggs-$10.00,Cheese-$20.00
 ```
 
 ## Class diagram
 
-![](./etc/domain-model.urm.png "domain model")
+![Domain Model class diagram](./etc/domain-model.urm.png "domain model")
 
 ## Applicability
 
-Use a Domain model pattern when your domain logic is complex and that complexity can rapidly grow because this pattern handles increasing complexity very well. Otherwise, it's a more complex solution for organizing domain logic, so shouldn't use Domain Model pattern for systems with simple domain logic, because the cost of understanding it and complexity of data source exceeds the benefit of this pattern.
+* Appropriate in complex applications with rich business logic.
+* When the business logic or domain complexity is high and requires a model that closely represents real-world entities and their relationships.
+* Suitable for applications where domain experts are involved in the development process to ensure the model accurately reflects domain concepts.
+
+## Known Uses
+
+* Enterprise applications (ERP, CRM systems)
+* Financial systems (banking, trading platforms)
+* Healthcare applications (patient records management)
+* E-commerce platforms (product catalogs, shopping carts)
+
+## Consequences
+
+Benefits:
 
-## Related patterns
+* Improved Communication: Provides a common language for developers and domain experts, enhancing understanding and collaboration.
+* Flexibility: Encapsulates business logic within domain entities, making it easier to modify and extend without affecting other system parts.
+* Maintainability: A well-structured domain model can simplify maintenance and evolution of the application over time.
+* Reusability: Domain classes can often be reused across different projects within the same domain.
 
-- [Transaction Script](https://java-design-patterns.com/patterns/transaction-script/)
+Trade-offs:
 
-- [Table Module](https://java-design-patterns.com/patterns/table-module/)
-  
-- [Service Layer](https://java-design-patterns.com/patterns/service-layer/)
+* Complexity: Can introduce complexity, especially in simple applications where a domain model might be overkill.
+* Performance Concerns: Rich domain objects with complex behaviors might lead to performance bottlenecks, requiring careful optimization.
+* Learning Curve: Requires a good understanding of the domain and may involve a steep learning curve for developers unfamiliar with the domain concepts.
+
+## Related Patterns
+
+* [Data Access Object (DAO)](https://java-design-patterns.com/patterns/dao/): For abstracting and encapsulating all access to the data source.
+* [Service Layer](https://java-design-patterns.com/patterns/service-layer/): Defines an application's boundary with a layer of services that establishes a set of available operations and coordinates the application's response in each operation.
+* [Repository](https://java-design-patterns.com/patterns/repository/): Mediates between the domain and data mapping layers, acting like an in-memory domain object collection.
+* [Unit of Work](https://java-design-patterns.com/patterns/unit-of-work/): Maintains a list of objects affected by a business transaction and coordinates the writing out of changes.
 
 ## Credits
 
-* [Domain Model Pattern](https://martinfowler.com/eaaCatalog/domainModel.html)
+* [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://amzn.to/3vMCjnP)
+* [Implementing Domain-Driven Design](https://amzn.to/4cUX4OL)
 * [Patterns of Enterprise Application Architecture](https://www.amazon.com/gp/product/0321127420/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=0321127420&linkId=18acc13ba60d66690009505577c45c04)
+* [Domain Model Pattern](https://martinfowler.com/eaaCatalog/domainModel.html)
 * [Architecture patterns: domain model and friends](https://inviqa.com/blog/architecture-patterns-domain-model-and-friends)