Designing Immutable Classes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

import java.util.List;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Objects;
 
/**
 * A properly designed immutable class in Java.
 * 
 * ✓ Class is final — cannot be subclassed
 * ✓ All fields are private and final
 * ✓ No setter methods
 * ✓ Defensive copying for mutable inputs
 * ✓ Defensive copying (or unmodifiable view) for outputs
 */
public final class ImmutablePerson {
    
    // RULE 1: All fields private and final
    private final String name;
    private final int age;
    private final List<String> hobbies;  // Mutable type — requires special handling
    
    // RULE 5: Defensive copy on construction
    public ImmutablePerson(String name, int age, List<String> hobbies) {
        this.name = name;  // String is immutable — no copy needed
        this.age = age;     // Primitives are immutable by nature
        
        // CRITICAL: Defensive copy of mutable collection
        // Without this, caller could modify our internal state!
        this.hobbies = new ArrayList<>(hobbies);
    }
    
    // RULE 2: No setters — only getters
    public String getName() {
        return name;  // String is immutable — direct return is safe
    }
    
    public int getAge() {
        return age;  // Primitive — direct return is safe
    }
    
    public List<String> getHobbies() {
        // RULE 5: Return unmodifiable view — prevents external mutation
        // Alternative: return new ArrayList<>(hobbies) — defensive copy
        return Collections.unmodifiableList(hobbies);
    }
    
    // RULE 2: "Modification" methods return NEW objects
    public ImmutablePerson withName(String newName) {
        return new ImmutablePerson(newName, this.age, this.hobbies);
    }
    
    public ImmutablePerson withAge(int newAge) {
        return new ImmutablePerson(this.name, newAge, this.hobbies);
    }
    
    public ImmutablePerson withHobby(String newHobby) {
        List<String> newHobbies = new ArrayList<>(this.hobbies);
        newHobbies.add(newHobby);
        return new ImmutablePerson(this.name, this.age, newHobbies);
    }
    
    // Value-based equality for immutable objects
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        ImmutablePerson that = (ImmutablePerson) o;
        return age == that.age && 
               Objects.equals(name, that.name) && 
               Objects.equals(hobbies, that.hobbies);
    }
    
    @Override
    public int hashCode() {
        return Objects.hash(name, age, hobbies);
    }
    
    @Override
    public String toString() {
        return "ImmutablePerson{name='" + name + "', age=" + age + 
               ", hobbies=" + hobbies + "}";
    }
}
 
// Usage example:
ImmutablePerson alice = new ImmutablePerson(
    "Alice", 30, List.of("Reading", "Hiking")
);
 
// "Modification" creates new object; original unchanged
ImmutablePerson olderAlice = alice.withAge(31);
ImmutablePerson aliceWithNewHobby = alice.withHobby("Cooking");
 
System.out.println(alice);              // age=30, hobbies=[Reading, Hiking]
System.out.println(olderAlice);         // age=31
System.out.println(aliceWithNewHobby);  // hobbies=[Reading, Hiking, Cooking]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

from dataclasses import dataclass
from typing import Tuple
 
# All components are immutable
@dataclass(frozen=True)
class Address:
    street: str
    city: str
    postal_code: str
    country: str
 
@dataclass(frozen=True)
class ContactInfo:
    email: str
    phone: str
 
@dataclass(frozen=True)
class Person:
    """
    Composed entirely of immutable types:
    - str, int — primitives
    - Address, ContactInfo — frozen dataclasses
    - Tuple — immutable sequence
    """
    name: str
    age: int
    address: Address  # Immutable nested object
    contact: ContactInfo  # Immutable nested object
    tags: Tuple[str, ...]  # Immutable collection
    
    # Update methods create new instances at every level
    def with_address(self, new_address: Address) -> 'Person':
        return Person(
            self.name, self.age, new_address, 
            self.contact, self.tags
        )
    
    def with_city(self, new_city: str) -> 'Person':
        """Update nested value — creates new Address AND new Person"""
        new_address = Address(
            self.address.street,
            new_city,  # Only city changes
            self.address.postal_code,
            self.address.country
        )
        return self.with_address(new_address)
    
    def with_tag(self, tag: str) -> 'Person':
        return Person(
            self.name, self.age, self.address,
            self.contact, self.tags + (tag,)
        )
 
# Usage:
alice = Person(
    name="Alice",
    age=30,
    address=Address("123 Main St", "Boston", "02101", "USA"),
    contact=ContactInfo("alice@example.com", "555-1234"),
    tags=("developer", "team-lead")
)
 
# Update nested city — creates new Address in new Person
alice_in_seattle = alice.with_city("Seattle")
 
# Original completely unchanged
print(f"Original city: {alice.address.city}")      # Boston
print(f"New city: {alice_in_seattle.address.city}") # Seattle
 
# The original alice object is frozen forever

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

import copy
from typing import Dict, List, Any
 
class ImmutableConfig:
    """
    Contains nested mutable structures (dicts, lists).
    Uses deep defensive copying for protection.
    """
    
    def __init__(self, settings: Dict[str, Any]):
        # DEEP copy on input — isolate from external changes
        self._settings = copy.deepcopy(settings)
        
        # Recursively freeze the structure
        self._settings = self._deep_freeze(self._settings)
    
    def _deep_freeze(self, obj):
        """Convert mutable containers to immutable equivalents"""
        if isinstance(obj, dict):
            return tuple((k, self._deep_freeze(v)) for k, v in sorted(obj.items()))
        elif isinstance(obj, list):
            return tuple(self._deep_freeze(item) for item in obj)
        elif isinstance(obj, set):
            return frozenset(self._deep_freeze(item) for item in obj)
        else:
            return obj  # Primitive or already immutable
    
    def get(self, *keys):
        """Navigate nested structure safely"""
        current = dict(self._settings)
        for key in keys:
            if isinstance(current, dict):
                current = current.get(key)
            elif isinstance(current, tuple):
                # Handle frozen dict (tuple of pairs)
                current = dict(current).get(key)
            else:
                current = None
            if current is None:
                return None
        return current
    
    def to_dict(self) -> Dict[str, Any]:
        """Return a mutable COPY — caller can modify without affecting us"""
        return self._unfreeze(self._settings)
    
    def _unfreeze(self, obj):
        """Convert back to mutable structures (for output copy)"""
        if isinstance(obj, tuple):
            # Check if it's a frozen dict (tuple of pairs)
            if obj and isinstance(obj[0], tuple) and len(obj[0]) == 2:
                return {k: self._unfreeze(v) for k, v in obj}
            else:
                return [self._unfreeze(item) for item in obj]
        elif isinstance(obj, frozenset):
            return set(self._unfreeze(item) for item in obj)
        else:
            return obj
    
    def with_setting(self, key: str, value: Any) -> 'ImmutableConfig':
        """Return new config with updated setting"""
        new_settings = self.to_dict()
        new_settings[key] = value
        return ImmutableConfig(new_settings)
    
    def __hash__(self):
        return hash(self._settings)
    
    def __eq__(self, other):
        return isinstance(other, ImmutableConfig) and self._settings == other._settings
 
# Usage:
original_dict = {
    "database": {
        "host": "localhost",
        "ports": [5432, 5433],
        "credentials": {"user": "admin", "pass": "secret"}
    },
    "cache": {"ttl": 300}
}
 
config = ImmutableConfig(original_dict)
 
# External modification doesn't affect config
original_dict["database"]["host"] = "hacked!"
print(f"Config still has: {config.to_dict()['database']['host']}")  # localhost
 
# Modification returns new config
config2 = config.with_setting("cache", {"ttl": 600})
print(f"Original TTL: {config.to_dict()['cache']['ttl']}")   # 300
print(f"New TTL: {config2.to_dict()['cache']['ttl']}")       # 600

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

import java.util.List;
import java.util.ArrayList;
import java.util.Collections;
import java.time.LocalDate;
 
/**
 * Immutable class with many fields — uses Builder pattern
 */
public final class ImmutableOrder {
    
    private final String orderId;
    private final String customerId;
    private final List<String> items;
    private final double total;
    private final String shippingAddress;
    private final String billingAddress;
    private final LocalDate orderDate;
    private final String couponCode;
    private final boolean giftWrap;
    private final String giftMessage;
    
    // Private constructor — only accessible via Builder
    private ImmutableOrder(Builder builder) {
        this.orderId = builder.orderId;
        this.customerId = builder.customerId;
        this.items = Collections.unmodifiableList(new ArrayList<>(builder.items));
        this.total = builder.total;
        this.shippingAddress = builder.shippingAddress;
        this.billingAddress = builder.billingAddress;
        this.orderDate = builder.orderDate;
        this.couponCode = builder.couponCode;
        this.giftWrap = builder.giftWrap;
        this.giftMessage = builder.giftMessage;
    }
    
    // Only getters, no setters
    public String getOrderId() { return orderId; }
    public String getCustomerId() { return customerId; }
    public List<String> getItems() { return items; }
    public double getTotal() { return total; }
    public String getShippingAddress() { return shippingAddress; }
    public String getBillingAddress() { return billingAddress; }
    public LocalDate getOrderDate() { return orderDate; }
    public String getCouponCode() { return couponCode; }
    public boolean isGiftWrap() { return giftWrap; }
    public String getGiftMessage() { return giftMessage; }
    
    // Static factory to get Builder
    public static Builder builder() {
        return new Builder();
    }
    
    // toBuilder() for creating modified copies
    public Builder toBuilder() {
        return new Builder()
            .orderId(this.orderId)
            .customerId(this.customerId)
            .items(new ArrayList<>(this.items))
            .total(this.total)
            .shippingAddress(this.shippingAddress)
            .billingAddress(this.billingAddress)
            .orderDate(this.orderDate)
            .couponCode(this.couponCode)
            .giftWrap(this.giftWrap)
            .giftMessage(this.giftMessage);
    }
    
    /**
     * Mutable Builder class — accumulates state, then produces immutable result
     */
    public static class Builder {
        private String orderId;
        private String customerId;
        private List<String> items = new ArrayList<>();
        private double total;
        private String shippingAddress;
        private String billingAddress;
        private LocalDate orderDate = LocalDate.now();  // Default
        private String couponCode = null;  // Optional
        private boolean giftWrap = false;  // Default
        private String giftMessage = null;  // Optional
        
        public Builder orderId(String orderId) {
            this.orderId = orderId;
            return this;
        }
        
        public Builder customerId(String customerId) {
            this.customerId = customerId;
            return this;
        }
        
        public Builder items(List<String> items) {
            this.items = new ArrayList<>(items);
            return this;
        }
        
        public Builder addItem(String item) {
            this.items.add(item);
            return this;
        }
        
        public Builder total(double total) {
            this.total = total;
            return this;
        }
        
        public Builder shippingAddress(String address) {
            this.shippingAddress = address;
            return this;
        }
        
        public Builder billingAddress(String address) {
            this.billingAddress = address;
            return this;
        }
        
        public Builder orderDate(LocalDate date) {
            this.orderDate = date;
            return this;
        }
        
        public Builder couponCode(String code) {
            this.couponCode = code;
            return this;
        }
        
        public Builder giftWrap(boolean giftWrap) {
            this.giftWrap = giftWrap;
            return this;
        }
        
        public Builder giftMessage(String message) {
            this.giftMessage = message;
            return this;
        }
        
        // Terminal operation — produces immutable object
        public ImmutableOrder build() {
            // Validation before building
            if (orderId == null) throw new IllegalStateException("orderId required");
            if (customerId == null) throw new IllegalStateException("customerId required");
            if (shippingAddress == null) throw new IllegalStateException("shippingAddress required");
            
            return new ImmutableOrder(this);
        }
    }
}
 
// Usage — clean, readable construction
ImmutableOrder order = ImmutableOrder.builder()
    .orderId("ORD-12345")
    .customerId("CUST-001")
    .addItem("Widget")
    .addItem("Gadget")
    .total(99.99)
    .shippingAddress("123 Main St, Boston")
    .billingAddress("123 Main St, Boston")
    .couponCode("SAVE10")
    .giftWrap(true)
    .giftMessage("Happy Birthday!")
    .build();
 
// Create modified copy using toBuilder()
ImmutableOrder updatedOrder = order.toBuilder()
    .addItem("Extra Item")
    .total(129.99)
    .build();
 
// Original is unchanged
System.out.println("Original items: " + order.getItems().size());  // 2
System.out.println("Updated items: " + updatedOrder.getItems().size()); // 3

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

from dataclasses import dataclass, replace
from typing import TypeVar, Callable
 
# Python's dataclasses have a built-in functional update: replace()
 
@dataclass(frozen=True)
class User:
    id: str
    name: str
    email: str
    role: str
    active: bool
    login_count: int
 
# Using dataclasses.replace() for functional updates
alice = User("1", "Alice", "alice@example.com", "admin", True, 42)
 
# replace() creates a new instance with specified fields changed
alice_v2 = replace(alice, name="Alice Smith")
alice_v3 = replace(alice, role="superadmin", login_count=43)
 
print(f"Original: {alice.name}, {alice.role}")  # Alice, admin
print(f"Updated: {alice_v2.name}, {alice_v3.role}")  # Alice Smith, superadmin
 
# ─────────────────────────────────────────────────────
 
# Pattern: Transform functions for complex updates
 
@dataclass(frozen=True)
class Account:
    id: str
    balance: float
    status: str
    transactions: tuple
    
    # Simple updates
    def with_balance(self, new_balance: float) -> 'Account':
        return replace(self, balance=new_balance)
    
    def with_status(self, new_status: str) -> 'Account':
        return replace(self, status=new_status)
    
    # Derived updates (transform based on current state)
    def credit(self, amount: float) -> 'Account':
        return self.with_balance(self.balance + amount)
    
    def debit(self, amount: float) -> 'Account':
        if amount > self.balance:
            raise ValueError("Insufficient funds")
        return self.with_balance(self.balance - amount)
    
    # Updates with side-data
    def with_transaction(self, tx: str) -> 'Account':
        return replace(self, 
            transactions=self.transactions + (tx,)
        )
    
    # Compound updates
    def apply_interest(self, rate: float) -> 'Account':
        interest = self.balance * rate
        return (self
            .credit(interest)
            .with_transaction(f"Interest applied: {interest:.2f}"))
    
    # Conditional updates
    def close(self) -> 'Account':
        if self.balance != 0:
            raise ValueError("Cannot close account with non-zero balance")
        return self.with_status("closed")
 
# Usage — chain functional updates
account = Account("ACC-001", 1000.0, "active", ())
 
account = (account
    .credit(500)
    .with_transaction("Deposit: 500")
    .apply_interest(0.01)  # 1% interest
    .debit(100)
    .with_transaction("Withdrawal: 100"))
 
print(f"Final balance: {account.balance}")
print(f"Transactions: {account.transactions}")
 
# ─────────────────────────────────────────────────────
 
# Pattern: Lens-like updates for nested structures
 
@dataclass(frozen=True)
class Address:
    city: str
    street: str
 
@dataclass(frozen=True)
class Profile:
    name: str
    address: Address
    
    def with_city(self, city: str) -> 'Profile':
        """Update nested city through Profile"""
        return replace(self, 
            address=replace(self.address, city=city))
    
    def with_street(self, street: str) -> 'Profile':
        return replace(self,
            address=replace(self.address, street=street))
 
# Deeply nested update made simple
profile = Profile("Alice", Address("Boston", "123 Main"))
profile = profile.with_city("Seattle")
 
print(f"New city: {profile.address.city}")  # Seattle