Reading UML class and sequence diagrams

Python · checkout/lifetimes.py

"""The checkout design at work, and what composition means for lifetimes, measured with weak references."""
import weakref

from order import CardPayment, Order, Product, WalletPayment

catalogue = [Product("tea", 250), Product("biscuits", 120)]  # products exist before any order

order = Order()
order.add(catalogue[0], 2)
order.add(catalogue[1], 1)
print("total:", order.total())
print(order.checkout(CardPayment("4242")))
print(order.checkout(WalletPayment("w-17")))

try:
    order.items().append("a line item made outside the order")
except AttributeError as error:
    print("items() is read-only:", type(error).__name__)

item = weakref.ref(order.items()[0])
product = weakref.ref(catalogue[0])
del order  # the last reference to the order goes away
print("line item alive after the order is gone:", item() is not None)
print("product alive after the order is gone:", product() is not None)

total: 620
card ending 4242 charged 620
wallet w-17 debited 620
items() is read-only: AttributeError
line item alive after the order is gone: False
product alive after the order is gone: True

checkout/order.py

"""The checkout design of the class diagram: an Order composed of LineItems that refer to Products, and an Order
that depends on the PaymentMethod interface, which CardPayment and WalletPayment realise."""
from abc import ABC, abstractmethod
from dataclasses import dataclass


@dataclass(frozen=True)
class Product:
    name: str
    price: int  # in the currency's smallest unit, so that totals stay exact


class LineItem:
    """A part of exactly one Order: only Order.add() creates line items."""

    def __init__(self, product, qty):
        self.product = product  # association: the product exists without this line item
        self.qty = qty

    def subtotal(self):
        return self.product.price * self.qty


class PaymentMethod(ABC):
    """The interface: anything that can take a payment of an amount."""

    @abstractmethod
    def pay(self, amount):
        """Take the payment and return a receipt line."""


class CardPayment(PaymentMethod):  # realisation
    def __init__(self, last4):
        self._last4 = last4

    def pay(self, amount):
        return f"card ending {self._last4} charged {amount}"


class WalletPayment(PaymentMethod):  # realisation
    def __init__(self, wallet_id):
        self._wallet_id = wallet_id

    def pay(self, amount):
        return f"wallet {self._wallet_id} debited {amount}"


class Order:
    """The whole: it creates its line items, keeps them private and hands out only a copy."""

    def __init__(self):
        self._items = []  # composition: these line items live and die with this order

    def add(self, product, qty):
        self._items.append(LineItem(product, qty))

    def items(self):
        return tuple(self._items)

    def total(self):
        return sum(item.subtotal() for item in self._items)

    def checkout(self, method):
        # dependency: method is a parameter only, and the order keeps no reference to it
        return method.pay(self.total())

java/Checkout.java

import java.util.ArrayList;
import java.util.List;

/** The checkout design of the class diagram in Java: the same classes and relationships as order.py. */
public class Checkout {

    record Product(String name, int price) {}

    /** The interface: anything that can take a payment of an amount. */
    interface PaymentMethod {
        String pay(int amount);
    }

    static final class CardPayment implements PaymentMethod { // realisation
        private final String last4;

        CardPayment(String last4) {
            this.last4 = last4;
        }

        @Override
        public String pay(int amount) {
            return "card ending " + last4 + " charged " + amount;
        }
    }

    static final class WalletPayment implements PaymentMethod { // realisation
        private final String walletId;

        WalletPayment(String walletId) {
            this.walletId = walletId;
        }

        @Override
        public String pay(int amount) {
            return "wallet " + walletId + " debited " + amount;
        }
    }

    /** The whole: it creates its line items, keeps them private and hands out only a read-only copy. */
    static final class Order {

        /** A part of exactly one Order: the constructor is private, so only Order can call it. */
        static final class LineItem {
            final Product product; // association: the product exists without this line item
            final int qty;

            private LineItem(Product product, int qty) {
                this.product = product;
                this.qty = qty;
            }

            int subtotal() {
                return product.price() * qty;
            }
        }

        private final List<LineItem> items = new ArrayList<>(); // composition

        void add(Product product, int qty) {
            items.add(new LineItem(product, qty));
        }

        List<LineItem> items() {
            return List.copyOf(items);
        }

        int total() {
            return items.stream().mapToInt(LineItem::subtotal).sum();
        }

        String checkout(PaymentMethod method) { // dependency: a parameter only
            return method.pay(total());
        }
    }

    public static void main(String[] args) {
        List<Product> catalogue = List.of(new Product("tea", 250), new Product("biscuits", 120));
        Order order = new Order();
        order.add(catalogue.get(0), 2);
        order.add(catalogue.get(1), 1);
        System.out.println("total: " + order.total());
        System.out.println(order.checkout(new CardPayment("4242")));
        System.out.println(order.checkout(new WalletPayment("w-17")));
        try {
            order.items().add(null);
        } catch (UnsupportedOperationException error) {
            System.out.println("items() is read-only: " + error.getClass().getSimpleName());
        }
    }
}

java/session.py

"""Builds and runs Checkout.java as you would in a terminal, and prints the session.

javac --release 25 compiles against the Java 25 language and API, so the code uses nothing newer than Java 25
whatever the version of the JDK. The JDK here is Homebrew's OpenJDK; its version line is printed first, without the
release date that follows it.
"""
import os
import re
import subprocess

JDK_BIN = "/opt/homebrew/opt/openjdk/bin"
env = dict(os.environ, PATH=os.pathsep.join([JDK_BIN, os.environ.get("PATH", "")]))


def run(command):
    return subprocess.run(command, shell=True, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)


version = run("java -version").stdout.splitlines()
print("#", re.sub(r"\s+\d{4}-\d{2}-\d{2}", "", version[0]) if version else "java: not found")
for command in ("javac --release 25 -d classes Checkout.java", "java -cp classes Checkout"):
    print(f"$ {command}")
    result = run(command)
    print(result.stdout, end="")
    if result.returncode != 0:
        print(f"[exit status {result.returncode}]")
        raise SystemExit(1)

# openjdk version "27"
$ javac --release 25 -d classes Checkout.java
$ java -cp classes Checkout
total: 620
card ending 4242 charged 620
wallet w-17 debited 620
items() is read-only: UnsupportedOperationException

Python · checkout/trace_checkout.py

"""Records the calls that adding an item and checking out make, and prints them as a D2 sequence diagram."""
import functools

import order as design
from order import CardPayment, Order, Product

lines = ["shape: sequence_diagram"]
names = {}
caller = ["shop"]  # who is making the current call: the code at the bottom of this file starts as "shop"


def name_of(value):
    return names.get(id(value), str(value))


def lifeline(obj, name):
    names[id(obj)] = name
    lines.append(f'{name}: "{name}: {type(obj).__name__}"')


def traced(cls, method):
    original = getattr(cls, method)

    @functools.wraps(original)
    def wrapper(self, *args):
        source, target = caller[-1], name_of(self)
        shown = ", ".join(name_of(a) if id(a) in names else repr(a) if isinstance(a, str) else str(a) for a in args)
        lines.append(f'{source} -> {target}: "{method}({shown})"')
        caller.append(target)
        result = original(self, *args)
        caller.pop()
        if result is not None:  # a call that returns nothing gets no reply arrow
            lines.append(f'{target} -> {source}: "{result}" {{style.stroke-dash: 4}}')
        return result

    setattr(cls, method, wrapper)


def creating(cls, prefix):
    original = cls.__init__
    count = [0]

    @functools.wraps(original)
    def wrapper(self, *args):
        original(self, *args)
        count[0] += 1
        lifeline(self, f"{prefix}{count[0]}")
        lines.append(f'{caller[-1]} -> {prefix}{count[0]}: "«create»" {{style.stroke-dash: 4}}')

    cls.__init__ = wrapper


for cls, method in [(Order, "add"), (Order, "total"), (Order, "checkout"), (design.LineItem, "subtotal"), (CardPayment, "pay")]:
    traced(cls, method)
creating(design.LineItem, "item")

lines.append("shop")
basket = Order()
lifeline(basket, "order")
tea = Product("tea", 250)
names[id(tea)] = "tea"
basket.add(tea, 2)
card = CardPayment("4242")
lifeline(card, "card")
basket.checkout(card)
print("\n".join(lines))

shape: sequence_diagram
shop
order: "order: Order"
shop -> order: "add(tea, 2)"
item1: "item1: LineItem"
order -> item1: "«create»" {style.stroke-dash: 4}
card: "card: CardPayment"
shop -> order: "checkout(card)"
order -> order: "total()"
order -> item1: "subtotal()"
item1 -> order: "500" {style.stroke-dash: 4}
order -> order: "500" {style.stroke-dash: 4}
order -> card: "pay(500)"
card -> order: "card ending 4242 charged 500" {style.stroke-dash: 4}
order -> shop: "card ending 4242 charged 500" {style.stroke-dash: 4}

checkout/order.py

"""The checkout design of the class diagram: an Order composed of LineItems that refer to Products, and an Order
that depends on the PaymentMethod interface, which CardPayment and WalletPayment realise."""
from abc import ABC, abstractmethod
from dataclasses import dataclass


@dataclass(frozen=True)
class Product:
    name: str
    price: int  # in the currency's smallest unit, so that totals stay exact


class LineItem:
    """A part of exactly one Order: only Order.add() creates line items."""

    def __init__(self, product, qty):
        self.product = product  # association: the product exists without this line item
        self.qty = qty

    def subtotal(self):
        return self.product.price * self.qty


class PaymentMethod(ABC):
    """The interface: anything that can take a payment of an amount."""

    @abstractmethod
    def pay(self, amount):
        """Take the payment and return a receipt line."""


class CardPayment(PaymentMethod):  # realisation
    def __init__(self, last4):
        self._last4 = last4

    def pay(self, amount):
        return f"card ending {self._last4} charged {amount}"


class WalletPayment(PaymentMethod):  # realisation
    def __init__(self, wallet_id):
        self._wallet_id = wallet_id

    def pay(self, amount):
        return f"wallet {self._wallet_id} debited {amount}"


class Order:
    """The whole: it creates its line items, keeps them private and hands out only a copy."""

    def __init__(self):
        self._items = []  # composition: these line items live and die with this order

    def add(self, product, qty):
        self._items.append(LineItem(product, qty))

    def items(self):
        return tuple(self._items)

    def total(self):
        return sum(item.subtotal() for item in self._items)

    def checkout(self, method):
        # dependency: method is a parameter only, and the order keeps no reference to it
        return method.pay(self.total())