How to Create Immutable Class in Java: The "Stone Tablet" Approach

Imagine you’re signing a contract for a new house. Once the ink is dry and the document is notarized, you wouldn't want someone to come along and sneakily change the "Price" or the "Address" while you aren't looking, right? You want that document to be unchangeable.

In Java programming, we call this concept Immutability. An immutable object is like a message carved in stone: once it’s created, it can never be modified. In this guide, we’ll explore how to create immutable class structures that make your code safer, faster, and much easier to debug.

Core Concepts: Why Go Immutable?

When you learn Java, you often start with "Mutable" objects—objects where you can change fields using setters. However, as applications grow (especially in multi-threaded environments), mutable objects can become a nightmare.

The 5 Golden Rules of Immutability:

To make a class truly immutable, you must follow these steps:

1. Don't provide "setter" methods (methods that modify fields).
2. Make all fields final and private.
3. Make the class final so it cannot be extended (subclassed).
4. Deep Copy for Mutable Fields: If your class contains a reference to a mutable object (like a List or a Date), never return the original reference. Always return a copy.
5. Initialize all fields via the constructor.

Benefits:

• Thread Safety: Since the state never changes, multiple threads can access the object without synchronization issues.
• Caching: You can safely cache immutable objects because their hash code will never change.
• Security: Sensitive data (like usernames or passwords) can’t be tampered with after creation.

Code Examples (Java 21)

1. The Classic Way (Boilerplate Heavy)

This is the traditional way to create an immutable class. Notice how we handle the List to prevent outside modification.

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

// Rule 3: Final class
public final class UserProfile {
    // Rule 2: Private final fields
    private final String username;
    private final List<String> roles;

    // Rule 5: Initialize via constructor
    public UserProfile(String username, List<String> roles) {
        this.username = username;
        // Rule 4: Deep copy the mutable list to prevent external changes
        this.roles = new ArrayList<>(roles);
    }

    // Rule 1: Only Getters, no Setters
    public String getUsername() {
        return username;
    }

    public List<String> getRoles() {
        // Rule 4: Return an unmodifiable view
        return Collections.unmodifiableList(roles);
    }
}

2. The Modern Way: Java 21 Records

Java 16+ introduced Records, which are purpose-built for immutability. They handle all the boilerplate for you!

import java.util.List;

/**
 * In Java 21, a 'record' is immutable by default.
 * It automatically generates final fields, constructor, 
 * getters, equals, hashCode, and toString.
 */
public record SmartDevice(String deviceId, String model, List<String> permissions) {

    // Canonical constructor for deep copying
    public SmartDevice {
        // Ensure the list is immutable even if the caller changes the original
        permissions = List.copyOf(permissions);
    }
}

Practical Setup: Testing Immutability

If you were building a microservice (e.g., using Spring Boot), your "Response" would often be an immutable DTO.

Sample Request (cURL):

curl -X GET "http://localhost:8080/api/device/123"

Sample Response (JSON):

{
  "deviceId": "DEV-99",
  "model": "X-Sensor",
  "permissions": ["READ", "ALARM"]
}

Note: Because the Java object behind this JSON is a Record, you can be 100% sure the values won't change during the lifecycle of the request.

Best Practices

1. Prefer Records over Classes: If you are just holding data, use Java 21 record. It’s cleaner and less error-prone.
2. Beware of "Hidden" Mutability: If your class has a field like StringBuilder, remember that StringBuilder is mutable! Use String instead.
3. Check your Collections: Always use List.of(), Map.of(), or Collections.unmodifiableList() when returning collections.
4. Validate in the Constructor: Since the state can't change later, the constructor is the perfect place to ensure data is valid (e.g., checking if username is null).

Conclusion

Learning how to create immutable class patterns is a milestone in your journey to becoming a senior developer. It shifts your mindset from "how do I change this?" to "how do I represent this state?" This leads to fewer bugs and much more predictable code. Whether you use the classic final class approach or the modern record, immutability is a superpower you should use often.

Call to Action

Are you using Records in your projects yet, or are you sticking with classic classes? If you're hitting any roadblocks with deep copying or nested objects, leave a comment below! Let's discuss.