Encapsulation In Practice - Learning Module

Loading content...

0/246

Refactoring for Better Encapsulation

Improving Encapsulation Safely

Improving encapsulation in existing systems is fundamentally different from designing well-encapsulated code from scratch. Existing code has clients—other code that depends on its current interface. Changing that interface breaks those clients. This means refactoring for encapsulation must be done incrementally, safely, and with techniques that allow gradual migration.

This page presents a systematic methodology for encapsulation refactoring that you can apply to any codebase. We'll work through a realistic example transformation, explaining each step's rationale and mechanics.

What You Will Learn

By the end of this page, you'll understand how to analyze existing code for encapsulation weaknesses, plan refactoring in safe increments, use deprecation and wrapper patterns for gradual migration, and maintain backward compatibility during transformation.

The Refactoring Mindset

Before diving into techniques, we need to establish the right mindset for encapsulation refactoring.

Principles for Safe Refactoring

1. Preserve behavior first, improve structure second

Refactoring changes how code is organized without changing what it does. If tests pass before and after, you've refactored successfully. If behavior changes, you've introduced bugs.

2. Small steps with frequent commits

Each change should be atomic—compilable, testable, and independently mergeable. If something goes wrong, you can revert one small change, not hours of work.

3. Deprecate before deletion

Don't remove public APIs immediately. Mark them deprecated, provide migration paths, and give clients time to update. Remove in a later release.

4. Tests are your safety net

You must have test coverage before refactoring. If you don't, write characterization tests first—tests that capture current behavior, whatever it is.

The Refactoring Trap

The temptation is to fix everything at once—'while I'm in here, I'll also...' Resist this. Each refactoring should address one specific encapsulation issue. Mixing concerns makes changes harder to review, test, and revert if problems arise.

Step 1: Assess Encapsulation Violations

Before changing code, understand what's wrong and how it's used. This assessment guides your refactoring plan.

Case Study: The UserProfile Class

Consider this poorly encapsulated class that we'll refactor throughout this page:

UserProfile.java (Original)
Java
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
// Poorly encapsulated class - our refactoring target
public class UserProfile {
    public String id;
    public String username;
    public String email;
    public String passwordHash;
    public Date lastLogin;
    public List<String> roles;
    public Map<String, Object> preferences;
    public boolean isActive;
    
    public UserProfile() {
        roles = new ArrayList<>();
        preferences = new HashMap<>();
    }
    
    // Some utility methods
    public boolean hasRole(String role) {
        return roles.contains(role);
    }
    
    public Object getPreference(String key) {
        return preferences.get(key);
    }
}

Encapsulation Analysis

Before refactoring, catalog every violation:

Encapsulation Violation Inventory
Field	Problem	Risk Level	Usage Count*
id	Public mutable field (identity shouldn't change)	HIGH	47 direct accesses
username	Public mutable field	MEDIUM	23 direct accesses
email	Public mutable field (no validation)	HIGH	31 direct accesses
passwordHash	CRITICAL: Sensitive data publicly accessible	CRITICAL	8 direct accesses
lastLogin	Mutable Date exposed	MEDIUM	12 direct accesses
roles	Mutable collection exposed	HIGH	15 direct accesses
preferences	Mutable map exposed	MEDIUM	22 direct accesses
isActive	Public mutable, no audit trail	MEDIUM	19 direct accesses

How to Count Usages

Use your IDE's 'Find Usages' feature or grep for direct field access (e.g., grep -r 'profile\.email' src/). The count tells you how much work migration will require and helps prioritize which violations to fix first.

Prioritization

Based on the analysis:

CRITICAL: passwordHash — Security issue, fix immediately
HIGH: id, email, roles — Core invariants at risk
MEDIUM: username, isActive, preferences, lastLogin — Problematic but lower immediate risk

We'll address these in priority order, showing the refactoring techniques for each.

Step 2: Fix Critical Violations First

The passwordHash field being public is a security vulnerability. This gets fixed immediately, even if it breaks some clients.

The Transformation

Step 1: Encapsulate passwordHash
Java
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
public class UserProfile {
    // Changed: private, no getter (password should never be read out)
    private String passwordHash;
    
    // Other fields still public for now (we'll fix them incrementally)
    public String id;
    public String username;
    public String email;
    // ... rest unchanged
    
    // Constructor updated
    public UserProfile(String id, String passwordHash) {
        this.id = id;
        this.passwordHash = passwordHash;
        this.roles = new ArrayList<>();
        this.preferences = new HashMap<>();
    }
    
    // Password operations - don't expose hash, just operations on it
    public boolean verifyPassword(String candidatePassword) {
        // Use proper password hashing library
        return PasswordHasher.verify(candidatePassword, this.passwordHash);
    }
    
    public void changePassword(String currentPassword, String newPassword) {
        if (!verifyPassword(currentPassword)) {
            throw new InvalidPasswordException("Current password incorrect");
        }
        validatePasswordStrength(newPassword);
        this.passwordHash = PasswordHasher.hash(newPassword);
    }
    
    // Administrative password reset (separate privilege check needed)
    public void resetPassword(String newPassword) {
        validatePasswordStrength(newPassword);
        this.passwordHash = PasswordHasher.hash(newPassword);
    }
    
    private void validatePasswordStrength(String password) {
        if (password == null || password.length() < 12) {
            throw new WeakPasswordException("Password must be at least 12 characters");
        }
        // Additional strength checks...
    }
}

Security Through Encapsulation

The password hash is now completely hidden. There's no getter because no external code should ever read it. Operations like verification and changing happen inside the class where the hash lives. This is encapsulation serving security.

Finding and Fixing Callers

Search for all code that accessed passwordHash directly:

Client Code Migration
Java
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
// BEFORE: Direct hash access (found in AuthService.java)
public boolean authenticate(String username, String password) {
    UserProfile user = findByUsername(username);
    String hashed = hashPassword(password);
    return user.passwordHash.equals(hashed);  // 💀 Direct access
}
 
// AFTER: Using the new encapsulated method
public boolean authenticate(String username, String password) {
    UserProfile user = findByUsername(username);
    return user.verifyPassword(password);  // ✅ Operation, not data
}
 
// ---
 
// BEFORE: Direct hash modification (found in AdminController.java)
public void resetUserPassword(String userId, String newPassword) {
    UserProfile user = findById(userId);
    user.passwordHash = hashPassword(newPassword);  // 💀 Direct write
    save(user);
}
 
// AFTER: Using domain method
public void resetUserPassword(String userId, String newPassword) {
    UserProfile user = findById(userId);
    user.resetPassword(newPassword);  // ✅ Includes validation
    save(user);
}

Step 3: Gradual Migration with Deprecation

For non-critical violations, we use deprecation to allow gradual migration. This is especially important in libraries or systems with many clients.

The Deprecation Pattern

Gradual Migration: email field
Java
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
public class UserProfile {
    // STEP A: Make field private, add accessor
    private String email;
    
    /**
     * @deprecated Direct field access will be removed in v3.0.
     *             Use {@link #getEmail()} instead.
     */
    @Deprecated(since = "2.5", forRemoval = true)
    public String getEmailField() {
        return email;  // Temporary shim for migration
    }
    
    // New encapsulated accessors
    public String getEmail() {
        return email;
    }
    
    public void setEmail(String newEmail) {
        this.email = validateEmail(newEmail);
    }
    
    public void updateEmail(String newEmail, String verificationToken) {
        // Full email change process with verification
        if (!emailVerificationService.verify(verificationToken)) {
            throw new EmailVerificationException("Invalid token");
        }
        this.email = validateEmail(newEmail);
    }
    
    private String validateEmail(String email) {
        if (email == null || !EMAIL_PATTERN.matcher(email).matches()) {
            throw new InvalidEmailException("Invalid email format");
        }
        return email.toLowerCase();  // Normalize
    }
}

Migration Script for Clients

Provide clear migration guidance:

MIGRATION_GUIDE.md
Markdown
## UserProfile Migration Guide (v2.5 → v3.0)
 
### Email Access
 
**Before (deprecated):**
```java
String email = user.email;           // Direct field access
user.email = "new@example.com";      // Direct modification
```
 
**After:**
```java
String email = user.getEmail();      // Read via getter
user.setEmail("new@example.com");    // Write via validated setter
```
 
### Automated Fix
 
Run the provided migration script:
```bash
./scripts/migrate-user-profile.sh src/
```
 
This will update 90% of usages automatically. Manual review needed for:
- Dynamic field access via reflection
- Serialization configurations
- Generated code from frameworks

Deprecation Timeline

A typical timeline: v2.5 — Add getters/setters, deprecate direct access. v2.6 to v2.9 — Log warnings when deprecated APIs are used. v3.0 — Remove deprecated public fields/methods. This gives clients multiple release cycles to migrate.

Step 4: Encapsulate Collections

Collections require special handling because clients may have stored references to them. We need to maintain behavioral compatibility while preventing future modifications.

The Roles Collection Transformation

Encapsulating the roles collection
Java
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
public class UserProfile {
    // Changed: private, using Set for uniqueness
    private final Set<Role> roles;  // Not List<String> anymore
    
    public UserProfile(String id, String passwordHash) {
        this.id = id;
        this.passwordHash = passwordHash;
        this.roles = new HashSet<>();  // Mutable internally
        this.preferences = new HashMap<>();
    }
    
    /**
     * @deprecated Use domain methods: hasRole(), grantRole(), revokeRole()
     *             Returns unmodifiable snapshot; changes won't reflect.
     */
    @Deprecated(since = "2.5", forRemoval = true)
    public List<String> getRoles() {
        // Return what old callers expect: List<String>
        // But make it unmodifiable to prevent modification
        return roles.stream()
            .map(Role::getName)
            .collect(Collectors.toUnmodifiableList());
    }
    
    // New: Type-safe role operations
    public boolean hasRole(Role role) {
        return roles.contains(role);
    }
    
    public boolean hasRole(String roleName) {
        return roles.stream().anyMatch(r -> r.getName().equals(roleName));
    }
    
    public void grantRole(Role role, String grantedBy) {
        Objects.requireNonNull(role);
        if (roles.add(role)) {
            auditLog.record(new RoleGrantedEvent(this.id, role, grantedBy));
        }
    }
    
    public void revokeRole(Role role, String revokedBy) {
        Objects.requireNonNull(role);
        if (roles.remove(role)) {
            auditLog.record(new RoleRevokedEvent(this.id, role, revokedBy));
        }
    }
    
    public Set<Role> getRoleSet() {
        return Set.copyOf(roles);  // Defensive copy
    }
    
    public boolean isAdmin() {
        return hasRole(Role.ADMIN);
    }
    
    public boolean canAccessResource(Resource resource) {
        return roles.stream().anyMatch(r -> r.canAccess(resource));
    }
}

Improvements in This Refactoring

•Type safety — Changed from List<String> to Set<Role>. Role is now a validated type, not just any string.
•Uniqueness guaranteed — Set prevents duplicate role assignments.
•Audit trail — grantRole() and revokeRole() record who made changes and when.
•Backward compatibility — getRoles() still works but is deprecated; returns unmodifiable list.
•Domain methods — hasRole(), isAdmin(), canAccessResource() express intent better than raw collection access.

Step 5: Make Identity Immutable

The id field should never change after object creation. This is a fundamental invariant that encapsulation must enforce.

The Challenge

The problem is that id is currently a public field, and some code might be setting it. We need to find all such code and determine if it's:

Construction code — Legitimate, needs to set ID during creation
Modification code — Illegitimate, should be prevented

The Transformation

Making id immutable
Java
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
public class UserProfile {
    // FINAL: Cannot be changed after construction
    private final String id;
    
    // Private constructor - use factory methods or builder
    private UserProfile(String id, String passwordHash) {
        this.id = validateId(id);
        this.passwordHash = passwordHash;
        this.roles = new HashSet<>();
        this.preferences = new HashMap<>();
        this.isActive = true;
        this.createdAt = Instant.now();
    }
    
    // Factory for new users
    public static UserProfile createNew(String passwordHash) {
        String generatedId = IdGenerator.generateUserId();
        return new UserProfile(generatedId, passwordHash);
    }
    
    // Factory for reconstructing from database
    public static UserProfile fromDatabase(String id, String passwordHash,
            Set<Role> roles, Map<String, Object> preferences, boolean isActive) {
        UserProfile profile = new UserProfile(id, passwordHash);
        profile.roles.addAll(roles);
        profile.preferences.putAll(preferences);
        profile.isActive = isActive;
        return profile;
    }
    
    // Read-only access
    public String getId() {
        return id;
    }
    
    // Note: No setId() method exists - ID is permanently fixed
    
    private static String validateId(String id) {
        if (id == null || !id.matches("USR-[A-Z0-9]{8}")) {
            throw new IllegalArgumentException(
                "ID must match format: USR-XXXXXXXX"
            );
        }
        return id;
    }
}

Migrating ID Assignment Code

Before/After comparison
Java
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
// BEFORE: Direct ID assignment (found in UserRepository.java)
public UserProfile createUser(RegistrationRequest request) {
    UserProfile user = new UserProfile();
    user.id = idGenerator.next();  // 💀 Direct field write
    user.username = request.getUsername();
    user.email = request.getEmail();
    user.passwordHash = hashPassword(request.getPassword());
    return repository.save(user);
}
 
// AFTER: Using factory method
public UserProfile createUser(RegistrationRequest request) {
    UserProfile user = UserProfile.createNew(
        hashPassword(request.getPassword())
    );
    user.setUsername(request.getUsername());
    user.setEmail(request.getEmail());
    return repository.save(user);
}
 
// ---
 
// BEFORE: Reconstruction from database (UserMapper.java)
public UserProfile mapFromRow(ResultSet rs) {
    UserProfile user = new UserProfile();
    user.id = rs.getString("id");  // 💀 Direct write
    user.username = rs.getString("username");
    // ... map all fields
    return user;
}
 
// AFTER: Using reconstruction factory
public UserProfile mapFromRow(ResultSet rs) {
    return UserProfile.fromDatabase(
        rs.getString("id"),
        rs.getString("password_hash"),
        mapRoles(rs.getString("roles")),
        mapPreferences(rs.getString("preferences")),
        rs.getBoolean("is_active")
    );
}

Factory Methods Clarify Intent

Notice how createNew() and fromDatabase() communicate different use cases. The first generates a new ID; the second accepts an existing one. This is clearer than a single constructor that sometimes generates and sometimes accepts an ID.

The Refactored Class

After all transformations, here's the fully encapsulated UserProfile class:

UserProfile.java (Final)
Java
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
public final class UserProfile {
    // Immutable identity
    private final String id;
    private final Instant createdAt;
    
    // Validated mutable state
    private String username;
    private Email email;  // Value object
    private String passwordHash;
    private Instant lastLogin;
    
    // Protected collections
    private final Set<Role> roles;
    private final Map<String, Preference> preferences;
    
    // Controlled lifecycle
    private boolean isActive;
    
    // Audit support
    private static final AuditLog auditLog = AuditLog.getInstance();
    
    private UserProfile(String id, String passwordHash) {
        this.id = validateId(id);
        this.passwordHash = passwordHash;
        this.roles = new HashSet<>();
        this.preferences = new HashMap<>();
        this.isActive = true;
        this.createdAt = Instant.now();
    }
    
    // Factory methods
    public static UserProfile createNew(String password) {
        return new UserProfile(
            IdGenerator.generateUserId(),
            PasswordHasher.hash(password)
        );
    }
    
    public static UserProfile fromDatabase(UserProfileData data) {
        UserProfile profile = new UserProfile(data.id(), data.passwordHash());
        profile.username = data.username();
        profile.email = data.email();
        profile.lastLogin = data.lastLogin();
        profile.roles.addAll(data.roles());
        profile.preferences.putAll(data.preferences());
        profile.isActive = data.isActive();
        return profile;
    }
    
    // Identity access (immutable)
    public String getId() { return id; }
    public Instant getCreatedAt() { return createdAt; }
    
    // Profile information
    public String getUsername() { return username; }
    public Email getEmail() { return email; }  // Email is immutable value object
    public Instant getLastLogin() { return lastLogin; }
    
    public void updateProfile(String username, Email email) {
        this.username = validateUsername(username);
        this.email = Objects.requireNonNull(email);
    }
    
    // Password operations (no getter)
    public boolean verifyPassword(String candidate) {
        return PasswordHasher.verify(candidate, passwordHash);
    }
    
    public void changePassword(String current, String newPassword) {
        if (!verifyPassword(current)) {
            throw new InvalidPasswordException("Current password incorrect");
        }
        this.passwordHash = PasswordHasher.hash(validatePassword(newPassword));
        auditLog.record(new PasswordChangedEvent(id));
    }
    
    // Role operations
    public boolean hasRole(Role role) {
        return roles.contains(role);
    }
    
    public Set<Role> getRoles() {
        return Set.copyOf(roles);
    }
    
    public void grantRole(Role role, String grantedBy) {
        if (roles.add(Objects.requireNonNull(role))) {
            auditLog.record(new RoleGrantedEvent(id, role, grantedBy));
        }
    }
    
    public void revokeRole(Role role, String revokedBy) {
        if (roles.remove(Objects.requireNonNull(role))) {
            auditLog.record(new RoleRevokedEvent(id, role, revokedBy));
        }
    }
    
    // Preference operations
    public Optional<Preference> getPreference(String key) {
        return Optional.ofNullable(preferences.get(key));
    }
    
    public void setPreference(String key, Preference value) {
        preferences.put(validatePreferenceKey(key), value);
    }
    
    // Lifecycle
    public boolean isActive() { return isActive; }
    
    public void deactivate(String reason, String deactivatedBy) {
        if (!isActive) return;
        this.isActive = false;
        auditLog.record(new UserDeactivatedEvent(id, reason, deactivatedBy));
    }
    
    public void reactivate(String reactivatedBy) {
        if (isActive) return;
        this.isActive = true;
        auditLog.record(new UserReactivatedEvent(id, reactivatedBy));
    }
    
    public void recordLogin() {
        this.lastLogin = Instant.now();
    }
    
    // Private validation
    private static String validateId(String id) { /* ... */ }
    private static String validateUsername(String username) { /* ... */ }
    private static String validatePassword(String password) { /* ... */ }
    private static String validatePreferenceKey(String key) { /* ... */ }
}

Summary: Refactoring for Encapsulation

Let's consolidate the refactoring methodology:

Refactoring Steps

•Assess — Inventory all encapsulation violations and their usage counts.
•Prioritize — Fix critical (security) issues immediately; plan migration for others.
•Deprecate — Mark old APIs deprecated before removing; provide migration path.
•Transform incrementally — One field or concern at a time; keep commits atomic.
•Test continuously — Run tests after each change; add characterization tests first.
•Document — Provide migration guides for breaking changes.

Refactoring Techniques Summary
Situation	Technique
Critical security violation	Fix immediately, update all callers, no deprecation period
Public mutable field	Add getter/setter, deprecate field, make field private
Exposed collection	Return unmodifiable view/copy, add domain operation methods
Identity field mutable	Make final, use factory methods for construction
Related fields change independently	Remove individual setters, add atomic update method

What's next:

The final page in this module provides a practical encapsulation checklist—a systematic review process you can apply to any class design to verify proper encapsulation.

Page Complete

You now have a systematic methodology for improving encapsulation in existing code. Remember: small steps, continuous testing, and clear migration paths make refactoring safe and sustainable.

Refactoring for Better Encapsulation

Improving Encapsulation Safely

What You Will Learn

The Refactoring Mindset

Before diving into techniques, we need to establish the right mindset for encapsulation refactoring.

Principles for Safe Refactoring

1. Preserve behavior first, improve structure second

Refactoring changes how code is organized without changing what it does. If tests pass before and after, you've refactored successfully. If behavior changes, you've introduced bugs.

2. Small steps with frequent commits

Each change should be atomic—compilable, testable, and independently mergeable. If something goes wrong, you can revert one small change, not hours of work.

3. Deprecate before deletion

Don't remove public APIs immediately. Mark them deprecated, provide migration paths, and give clients time to update. Remove in a later release.

4. Tests are your safety net

You must have test coverage before refactoring. If you don't, write characterization tests first—tests that capture current behavior, whatever it is.

The Refactoring Trap

Step 1: Assess Encapsulation Violations

Before changing code, understand what's wrong and how it's used. This assessment guides your refactoring plan.

Case Study: The UserProfile Class

Consider this poorly encapsulated class that we'll refactor throughout this page:

UserProfile.java (Original)
Java
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
// Poorly encapsulated class - our refactoring target
public class UserProfile {
    public String id;
    public String username;
    public String email;
    public String passwordHash;
    public Date lastLogin;
    public List<String> roles;
    public Map<String, Object> preferences;
    public boolean isActive;
    
    public UserProfile() {
        roles = new ArrayList<>();
        preferences = new HashMap<>();
    }
    
    // Some utility methods
    public boolean hasRole(String role) {
        return roles.contains(role);
    }
    
    public Object getPreference(String key) {
        return preferences.get(key);
    }
}

Encapsulation Analysis

Before refactoring, catalog every violation:

Encapsulation Violation Inventory
Field	Problem	Risk Level	Usage Count*
id	Public mutable field (identity shouldn't change)	HIGH	47 direct accesses
username	Public mutable field	MEDIUM	23 direct accesses
email	Public mutable field (no validation)	HIGH	31 direct accesses
passwordHash	CRITICAL: Sensitive data publicly accessible	CRITICAL	8 direct accesses
lastLogin	Mutable Date exposed	MEDIUM	12 direct accesses
roles	Mutable collection exposed	HIGH	15 direct accesses
preferences	Mutable map exposed	MEDIUM	22 direct accesses
isActive	Public mutable, no audit trail	MEDIUM	19 direct accesses

How to Count Usages

Prioritization

Based on the analysis:

CRITICAL: passwordHash — Security issue, fix immediately
HIGH: id, email, roles — Core invariants at risk
MEDIUM: username, isActive, preferences, lastLogin — Problematic but lower immediate risk

We'll address these in priority order, showing the refactoring techniques for each.

Step 2: Fix Critical Violations First

The passwordHash field being public is a security vulnerability. This gets fixed immediately, even if it breaks some clients.

The Transformation

Step 1: Encapsulate passwordHash
Java
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
public class UserProfile {
    // Changed: private, no getter (password should never be read out)
    private String passwordHash;
    
    // Other fields still public for now (we'll fix them incrementally)
    public String id;
    public String username;
    public String email;
    // ... rest unchanged
    
    // Constructor updated
    public UserProfile(String id, String passwordHash) {
        this.id = id;
        this.passwordHash = passwordHash;
        this.roles = new ArrayList<>();
        this.preferences = new HashMap<>();
    }
    
    // Password operations - don't expose hash, just operations on it
    public boolean verifyPassword(String candidatePassword) {
        // Use proper password hashing library
        return PasswordHasher.verify(candidatePassword, this.passwordHash);
    }
    
    public void changePassword(String currentPassword, String newPassword) {
        if (!verifyPassword(currentPassword)) {
            throw new InvalidPasswordException("Current password incorrect");
        }
        validatePasswordStrength(newPassword);
        this.passwordHash = PasswordHasher.hash(newPassword);
    }
    
    // Administrative password reset (separate privilege check needed)
    public void resetPassword(String newPassword) {
        validatePasswordStrength(newPassword);
        this.passwordHash = PasswordHasher.hash(newPassword);
    }
    
    private void validatePasswordStrength(String password) {
        if (password == null || password.length() < 12) {
            throw new WeakPasswordException("Password must be at least 12 characters");
        }
        // Additional strength checks...
    }
}

Security Through Encapsulation

Finding and Fixing Callers

Search for all code that accessed passwordHash directly:

Client Code Migration
Java
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
// BEFORE: Direct hash access (found in AuthService.java)
public boolean authenticate(String username, String password) {
    UserProfile user = findByUsername(username);
    String hashed = hashPassword(password);
    return user.passwordHash.equals(hashed);  // 💀 Direct access
}
 
// AFTER: Using the new encapsulated method
public boolean authenticate(String username, String password) {
    UserProfile user = findByUsername(username);
    return user.verifyPassword(password);  // ✅ Operation, not data
}
 
// ---
 
// BEFORE: Direct hash modification (found in AdminController.java)
public void resetUserPassword(String userId, String newPassword) {
    UserProfile user = findById(userId);
    user.passwordHash = hashPassword(newPassword);  // 💀 Direct write
    save(user);
}
 
// AFTER: Using domain method
public void resetUserPassword(String userId, String newPassword) {
    UserProfile user = findById(userId);
    user.resetPassword(newPassword);  // ✅ Includes validation
    save(user);
}

Step 3: Gradual Migration with Deprecation

For non-critical violations, we use deprecation to allow gradual migration. This is especially important in libraries or systems with many clients.

The Deprecation Pattern

Gradual Migration: email field
Java
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
public class UserProfile {
    // STEP A: Make field private, add accessor
    private String email;
    
    /**
     * @deprecated Direct field access will be removed in v3.0.
     *             Use {@link #getEmail()} instead.
     */
    @Deprecated(since = "2.5", forRemoval = true)
    public String getEmailField() {
        return email;  // Temporary shim for migration
    }
    
    // New encapsulated accessors
    public String getEmail() {
        return email;
    }
    
    public void setEmail(String newEmail) {
        this.email = validateEmail(newEmail);
    }
    
    public void updateEmail(String newEmail, String verificationToken) {
        // Full email change process with verification
        if (!emailVerificationService.verify(verificationToken)) {
            throw new EmailVerificationException("Invalid token");
        }
        this.email = validateEmail(newEmail);
    }
    
    private String validateEmail(String email) {
        if (email == null || !EMAIL_PATTERN.matcher(email).matches()) {
            throw new InvalidEmailException("Invalid email format");
        }
        return email.toLowerCase();  // Normalize
    }
}

Migration Script for Clients

Provide clear migration guidance:

MIGRATION_GUIDE.md
Markdown
## UserProfile Migration Guide (v2.5 → v3.0)
 
### Email Access
 
**Before (deprecated):**
```java
String email = user.email;           // Direct field access
user.email = "new@example.com";      // Direct modification
```
 
**After:**
```java
String email = user.getEmail();      // Read via getter
user.setEmail("new@example.com");    // Write via validated setter
```
 
### Automated Fix
 
Run the provided migration script:
```bash
./scripts/migrate-user-profile.sh src/
```
 
This will update 90% of usages automatically. Manual review needed for:
- Dynamic field access via reflection
- Serialization configurations
- Generated code from frameworks

Deprecation Timeline

Step 4: Encapsulate Collections

Collections require special handling because clients may have stored references to them. We need to maintain behavioral compatibility while preventing future modifications.

The Roles Collection Transformation

Encapsulating the roles collection
Java
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
public class UserProfile {
    // Changed: private, using Set for uniqueness
    private final Set<Role> roles;  // Not List<String> anymore
    
    public UserProfile(String id, String passwordHash) {
        this.id = id;
        this.passwordHash = passwordHash;
        this.roles = new HashSet<>();  // Mutable internally
        this.preferences = new HashMap<>();
    }
    
    /**
     * @deprecated Use domain methods: hasRole(), grantRole(), revokeRole()
     *             Returns unmodifiable snapshot; changes won't reflect.
     */
    @Deprecated(since = "2.5", forRemoval = true)
    public List<String> getRoles() {
        // Return what old callers expect: List<String>
        // But make it unmodifiable to prevent modification
        return roles.stream()
            .map(Role::getName)
            .collect(Collectors.toUnmodifiableList());
    }
    
    // New: Type-safe role operations
    public boolean hasRole(Role role) {
        return roles.contains(role);
    }
    
    public boolean hasRole(String roleName) {
        return roles.stream().anyMatch(r -> r.getName().equals(roleName));
    }
    
    public void grantRole(Role role, String grantedBy) {
        Objects.requireNonNull(role);
        if (roles.add(role)) {
            auditLog.record(new RoleGrantedEvent(this.id, role, grantedBy));
        }
    }
    
    public void revokeRole(Role role, String revokedBy) {
        Objects.requireNonNull(role);
        if (roles.remove(role)) {
            auditLog.record(new RoleRevokedEvent(this.id, role, revokedBy));
        }
    }
    
    public Set<Role> getRoleSet() {
        return Set.copyOf(roles);  // Defensive copy
    }
    
    public boolean isAdmin() {
        return hasRole(Role.ADMIN);
    }
    
    public boolean canAccessResource(Resource resource) {
        return roles.stream().anyMatch(r -> r.canAccess(resource));
    }
}

Improvements in This Refactoring

•Type safety — Changed from List<String> to Set<Role>. Role is now a validated type, not just any string.
•Uniqueness guaranteed — Set prevents duplicate role assignments.
•Audit trail — grantRole() and revokeRole() record who made changes and when.
•Backward compatibility — getRoles() still works but is deprecated; returns unmodifiable list.
•Domain methods — hasRole(), isAdmin(), canAccessResource() express intent better than raw collection access.

Step 5: Make Identity Immutable

The id field should never change after object creation. This is a fundamental invariant that encapsulation must enforce.

The Challenge

The problem is that id is currently a public field, and some code might be setting it. We need to find all such code and determine if it's:

Construction code — Legitimate, needs to set ID during creation
Modification code — Illegitimate, should be prevented

The Transformation

Making id immutable
Java
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
public class UserProfile {
    // FINAL: Cannot be changed after construction
    private final String id;
    
    // Private constructor - use factory methods or builder
    private UserProfile(String id, String passwordHash) {
        this.id = validateId(id);
        this.passwordHash = passwordHash;
        this.roles = new HashSet<>();
        this.preferences = new HashMap<>();
        this.isActive = true;
        this.createdAt = Instant.now();
    }
    
    // Factory for new users
    public static UserProfile createNew(String passwordHash) {
        String generatedId = IdGenerator.generateUserId();
        return new UserProfile(generatedId, passwordHash);
    }
    
    // Factory for reconstructing from database
    public static UserProfile fromDatabase(String id, String passwordHash,
            Set<Role> roles, Map<String, Object> preferences, boolean isActive) {
        UserProfile profile = new UserProfile(id, passwordHash);
        profile.roles.addAll(roles);
        profile.preferences.putAll(preferences);
        profile.isActive = isActive;
        return profile;
    }
    
    // Read-only access
    public String getId() {
        return id;
    }
    
    // Note: No setId() method exists - ID is permanently fixed
    
    private static String validateId(String id) {
        if (id == null || !id.matches("USR-[A-Z0-9]{8}")) {
            throw new IllegalArgumentException(
                "ID must match format: USR-XXXXXXXX"
            );
        }
        return id;
    }
}

Migrating ID Assignment Code

Before/After comparison
Java
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
// BEFORE: Direct ID assignment (found in UserRepository.java)
public UserProfile createUser(RegistrationRequest request) {
    UserProfile user = new UserProfile();
    user.id = idGenerator.next();  // 💀 Direct field write
    user.username = request.getUsername();
    user.email = request.getEmail();
    user.passwordHash = hashPassword(request.getPassword());
    return repository.save(user);
}
 
// AFTER: Using factory method
public UserProfile createUser(RegistrationRequest request) {
    UserProfile user = UserProfile.createNew(
        hashPassword(request.getPassword())
    );
    user.setUsername(request.getUsername());
    user.setEmail(request.getEmail());
    return repository.save(user);
}
 
// ---
 
// BEFORE: Reconstruction from database (UserMapper.java)
public UserProfile mapFromRow(ResultSet rs) {
    UserProfile user = new UserProfile();
    user.id = rs.getString("id");  // 💀 Direct write
    user.username = rs.getString("username");
    // ... map all fields
    return user;
}
 
// AFTER: Using reconstruction factory
public UserProfile mapFromRow(ResultSet rs) {
    return UserProfile.fromDatabase(
        rs.getString("id"),
        rs.getString("password_hash"),
        mapRoles(rs.getString("roles")),
        mapPreferences(rs.getString("preferences")),
        rs.getBoolean("is_active")
    );
}

Factory Methods Clarify Intent

The Refactored Class

After all transformations, here's the fully encapsulated UserProfile class:

UserProfile.java (Final)
Java
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
public final class UserProfile {
    // Immutable identity
    private final String id;
    private final Instant createdAt;
    
    // Validated mutable state
    private String username;
    private Email email;  // Value object
    private String passwordHash;
    private Instant lastLogin;
    
    // Protected collections
    private final Set<Role> roles;
    private final Map<String, Preference> preferences;
    
    // Controlled lifecycle
    private boolean isActive;
    
    // Audit support
    private static final AuditLog auditLog = AuditLog.getInstance();
    
    private UserProfile(String id, String passwordHash) {
        this.id = validateId(id);
        this.passwordHash = passwordHash;
        this.roles = new HashSet<>();
        this.preferences = new HashMap<>();
        this.isActive = true;
        this.createdAt = Instant.now();
    }
    
    // Factory methods
    public static UserProfile createNew(String password) {
        return new UserProfile(
            IdGenerator.generateUserId(),
            PasswordHasher.hash(password)
        );
    }
    
    public static UserProfile fromDatabase(UserProfileData data) {
        UserProfile profile = new UserProfile(data.id(), data.passwordHash());
        profile.username = data.username();
        profile.email = data.email();
        profile.lastLogin = data.lastLogin();
        profile.roles.addAll(data.roles());
        profile.preferences.putAll(data.preferences());
        profile.isActive = data.isActive();
        return profile;
    }
    
    // Identity access (immutable)
    public String getId() { return id; }
    public Instant getCreatedAt() { return createdAt; }
    
    // Profile information
    public String getUsername() { return username; }
    public Email getEmail() { return email; }  // Email is immutable value object
    public Instant getLastLogin() { return lastLogin; }
    
    public void updateProfile(String username, Email email) {
        this.username = validateUsername(username);
        this.email = Objects.requireNonNull(email);
    }
    
    // Password operations (no getter)
    public boolean verifyPassword(String candidate) {
        return PasswordHasher.verify(candidate, passwordHash);
    }
    
    public void changePassword(String current, String newPassword) {
        if (!verifyPassword(current)) {
            throw new InvalidPasswordException("Current password incorrect");
        }
        this.passwordHash = PasswordHasher.hash(validatePassword(newPassword));
        auditLog.record(new PasswordChangedEvent(id));
    }
    
    // Role operations
    public boolean hasRole(Role role) {
        return roles.contains(role);
    }
    
    public Set<Role> getRoles() {
        return Set.copyOf(roles);
    }
    
    public void grantRole(Role role, String grantedBy) {
        if (roles.add(Objects.requireNonNull(role))) {
            auditLog.record(new RoleGrantedEvent(id, role, grantedBy));
        }
    }
    
    public void revokeRole(Role role, String revokedBy) {
        if (roles.remove(Objects.requireNonNull(role))) {
            auditLog.record(new RoleRevokedEvent(id, role, revokedBy));
        }
    }
    
    // Preference operations
    public Optional<Preference> getPreference(String key) {
        return Optional.ofNullable(preferences.get(key));
    }
    
    public void setPreference(String key, Preference value) {
        preferences.put(validatePreferenceKey(key), value);
    }
    
    // Lifecycle
    public boolean isActive() { return isActive; }
    
    public void deactivate(String reason, String deactivatedBy) {
        if (!isActive) return;
        this.isActive = false;
        auditLog.record(new UserDeactivatedEvent(id, reason, deactivatedBy));
    }
    
    public void reactivate(String reactivatedBy) {
        if (isActive) return;
        this.isActive = true;
        auditLog.record(new UserReactivatedEvent(id, reactivatedBy));
    }
    
    public void recordLogin() {
        this.lastLogin = Instant.now();
    }
    
    // Private validation
    private static String validateId(String id) { /* ... */ }
    private static String validateUsername(String username) { /* ... */ }
    private static String validatePassword(String password) { /* ... */ }
    private static String validatePreferenceKey(String key) { /* ... */ }
}

Summary: Refactoring for Encapsulation

Let's consolidate the refactoring methodology:

Refactoring Steps

•Assess — Inventory all encapsulation violations and their usage counts.
•Prioritize — Fix critical (security) issues immediately; plan migration for others.
•Deprecate — Mark old APIs deprecated before removing; provide migration path.
•Transform incrementally — One field or concern at a time; keep commits atomic.
•Test continuously — Run tests after each change; add characterization tests first.
•Document — Provide migration guides for breaking changes.

Refactoring Techniques Summary
Situation	Technique
Critical security violation	Fix immediately, update all callers, no deprecation period
Public mutable field	Add getter/setter, deprecate field, make field private
Exposed collection	Return unmodifiable view/copy, add domain operation methods
Identity field mutable	Make final, use factory methods for construction
Related fields change independently	Remove individual setters, add atomic update method

What's next:

The final page in this module provides a practical encapsulation checklist—a systematic review process you can apply to any class design to verify proper encapsulation.

Page Complete

You now have a systematic methodology for improving encapsulation in existing code. Remember: small steps, continuous testing, and clear migration paths make refactoring safe and sustainable.