1
2
3
4
5
6
7
8
9
10
11
12
13

public class WellEncapsulated {
    // ✅ Constants: public static final is acceptable
    public static final int MAX_NAME_LENGTH = 100;
    public static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(30);
    
    // ✅ All instance fields are private
    private final String id;
    private String name;
    private Instant createdAt;
    
    // ⚠️ Protected only when inheritance contract requires it
    protected Logger logger;  // Subclasses can use parent's logger
}

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

public class Customer {
    private final String id;
    private String name;
    private Email email;
    private Address billingAddress;
    private List<Order> orderHistory;
    
    // ✅ ID getter: legitimate read-only access
    public String getId() { return id; }
    
    // ✅ Name getter: needed for display
    public String getName() { return name; }
    
    // ❌ NO getName setter - use updateProfile() instead
    
    // ✅ Domain operation instead of setter
    public void updateProfile(String name, Email email) {
        this.name = validateName(name);
        this.email = Objects.requireNonNull(email);
    }
    
    // ✅ Defensive copy prevents external modification
    public List<Order> getOrderHistory() {
        return List.copyOf(orderHistory);
    }
    
    // ✅ No billing address setter - separate operation with validation
    public void updateBillingAddress(Address newAddress, AddressValidator validator) {
        if (!validator.isValid(newAddress)) {
            throw new InvalidAddressException("Address validation failed");
        }
        this.billingAddress = newAddress;
    }
}

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

public class Order {
    // ALWAYS IMMUTABLE - Identity and history
    private final String orderId;
    private final String customerId;
    private final Instant createdAt;
    private final List<OrderLine> originalLines;  // Snapshot at creation
    
    // CONTROLLED MUTABILITY - Through methods only
    private OrderStatus status;  // Changed via lifecycle methods
    private Instant lastModified;  // Updated on any change
    
    // DERIVED/CALCULATED - Not stored
    public Money getTotal() {
        return originalLines.stream()
            .map(OrderLine::getLineTotal)
            .reduce(Money.ZERO, Money::add);
    }
    
    // STATUS CHANGES - Validated transitions
    public void confirm() {
        if (status != OrderStatus.PENDING) {
            throw new InvalidStateTransitionException("Can only confirm pending orders");
        }
        this.status = OrderStatus.CONFIRMED;
        this.lastModified = Instant.now();
    }
    
    public void ship(ShippingInfo shipping) {
        if (status != OrderStatus.CONFIRMED) {
            throw new InvalidStateTransitionException("Can only ship confirmed orders");
        }
        this.status = OrderStatus.SHIPPED;
        this.lastModified = Instant.now();
    }
}

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

public class Course {
    private final String courseId;
    private final Set<Student> enrolledStudents;
    private final List<Assignment> assignments;
    
    public Course(String courseId, Collection<Student> initialStudents) {
        this.courseId = courseId;
        // ✅ Defensive copy on INPUT
        this.enrolledStudents = new HashSet<>(initialStudents);
        this.assignments = new ArrayList<>();
    }
    
    // ✅ Return unmodifiable view - lightweight, reflects current state
    public Set<Student> getEnrolledStudents() {
        return Collections.unmodifiableSet(enrolledStudents);
    }
    
    // ✅ Return defensive copy - isolated snapshot
    public List<Assignment> getAssignmentsCopy() {
        return new ArrayList<>(assignments);
    }
    
    // ✅ Stream for functional processing
    public Stream<Assignment> assignments() {
        return assignments.stream();
    }
    
    // ✅ Domain operations for modification
    public void enrollStudent(Student student) {
        Objects.requireNonNull(student, "Student cannot be null");
        if (enrolledStudents.size() >= MAX_ENROLLMENT) {
            throw new CourseFullException("Course has reached maximum enrollment");
        }
        if (student.hasConflict(this.schedule)) {
            throw new ScheduleConflictException("Student has schedule conflict");
        }
        enrolledStudents.add(student);
    }
    
    public boolean dropStudent(String studentId) {
        return enrolledStudents.removeIf(s -> s.getId().equals(studentId));
    }
    
    public void addAssignment(Assignment assignment) {
        Objects.requireNonNull(assignment);
        if (assignments.stream().anyMatch(a -> a.getName().equals(assignment.getName()))) {
            throw new DuplicateAssignmentException("Assignment name already exists");
        }
        assignments.add(assignment);
    }
    
    // ✅ Query methods instead of exposing collection
    public int getEnrollmentCount() {
        return enrolledStudents.size();
    }
    
    public boolean isEnrolled(Student student) {
        return enrolledStudents.contains(student);
    }
    
    public Optional<Assignment> findAssignment(String name) {
        return assignments.stream()
            .filter(a -> a.getName().equals(name))
            .findFirst();
    }
}

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

public final class Reservation {
    private final String reservationId;
    private final String guestId;
    private final LocalDate checkIn;
    private final LocalDate checkOut;
    private ReservationStatus status;
    private int guestCount;
    
    // ✅ Private constructor - all validation done
    private Reservation(Builder builder) {
        // Non-null checks
        this.reservationId = Objects.requireNonNull(builder.reservationId);
        this.guestId = Objects.requireNonNull(builder.guestId);
        this.checkIn = Objects.requireNonNull(builder.checkIn);
        this.checkOut = Objects.requireNonNull(builder.checkOut);
        
        // Cross-field invariant
        if (!checkOut.isAfter(checkIn)) {
            throw new IllegalArgumentException("Check-out must be after check-in");
        }
        
        // Range constraint
        if (builder.guestCount < 1 || builder.guestCount > 10) {
            throw new IllegalArgumentException("Guest count must be 1-10");
        }
        this.guestCount = builder.guestCount;
        
        // Business rule
        long nights = ChronoUnit.DAYS.between(checkIn, checkOut);
        if (nights > 30) {
            throw new IllegalArgumentException("Maximum stay is 30 nights");
        }
        
        this.status = ReservationStatus.PENDING;
    }
    
    // ✅ State transition with validation
    public void confirm(PaymentInfo payment) {
        if (status != ReservationStatus.PENDING) {
            throw new InvalidStateException("Can only confirm pending reservations");
        }
        if (!payment.isValid()) {
            throw new PaymentException("Invalid payment information");
        }
        this.status = ReservationStatus.CONFIRMED;
    }
    
    public void cancel(String reason) {
        if (status == ReservationStatus.CHECKED_OUT) {
            throw new InvalidStateException("Cannot cancel completed stay");
        }
        if (status == ReservationStatus.CANCELLED) {
            return; // Idempotent
        }
        this.status = ReservationStatus.CANCELLED;
    }
    
    // ✅ Modification with invariant maintenance
    public void modifyDates(LocalDate newCheckIn, LocalDate newCheckOut) {
        // Can only modify pending reservations
        if (status != ReservationStatus.PENDING) {
            throw new InvalidStateException("Can only modify pending reservations");
        }
        
        // Validate new dates (same rules as construction)
        if (!newCheckOut.isAfter(newCheckIn)) {
            throw new IllegalArgumentException("Check-out must be after check-in");
        }
        
        long nights = ChronoUnit.DAYS.between(newCheckIn, newCheckOut);
        if (nights > 30) {
            throw new IllegalArgumentException("Maximum stay is 30 nights");
        }
        
        // Atomic update - both or neither
        // (Since these are final, we'd return a new Reservation in truly immutable design)
    }
    
    // ✅ Builder for complex construction
    public static class Builder {
        private String reservationId;
        private String guestId;
        private LocalDate checkIn;
        private LocalDate checkOut;
        private int guestCount = 1;
        
        public Builder reservationId(String id) { this.reservationId = id; return this; }
        public Builder guestId(String id) { this.guestId = id; return this; }
        public Builder checkIn(LocalDate date) { this.checkIn = date; return this; }
        public Builder checkOut(LocalDate date) { this.checkOut = date; return this; }
        public Builder guestCount(int count) { this.guestCount = count; return this; }
        
        public Reservation build() {
            return new Reservation(this);
        }
    }
}

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

public class UserService {
    // ✅ Implementation detail hidden - clients don't know it's Redis
    private final UserCache cache;  // Interface, not RedisCache
    private final UserRepository repository;  // Interface, not PostgresRepository
    
    public Optional<User> findById(String userId) {
        try {
            // Check cache first (implementation detail)
            Optional<User> cached = cache.get(userId);
            if (cached.isPresent()) {
                return cached;
            }
            
            // Fall back to database (implementation detail)
            Optional<User> fromDb = repository.findById(userId);
            fromDb.ifPresent(user -> cache.put(userId, user));
            return fromDb;
            
        } catch (CacheConnectionException e) {
            // ✅ Don't leak cache implementation details
            // Degrade gracefully, log internally
            logger.warn("Cache unavailable, falling back to database", e);
            return repository.findById(userId);
            
        } catch (DatabaseException e) {
            // ✅ Wrap implementation exception in domain exception
            throw new UserNotFoundException("User not found: " + userId, e);
        }
    }
    
    // ✅ Private helper - clients don't see this complexity
    private User enrichWithPermissions(User user) {
        Set<Permission> permissions = permissionService.getFor(user.getId());
        return user.withPermissions(permissions);
    }
    
    // ✅ Return type is interface, not implementation
    public List<User> findByDepartment(String department) {
        // Could return ArrayList, LinkedList, or unmodifiable - clients don't care
        return repository.findByDepartment(department);
    }
}