Immutables.org is a Java annotation processor that generates immutable objects, builders, and utility methods, eliminating the verbose boilerplate typically associated with writing immutable value classes in Java. By generating code at compile time, it provides the benefits of immutability with minimal developer effort.
Why Immutables.org?
Traditional Java Value Class:
// 50+ lines of boilerplate
public final class Person {
private final String name;
private final int age;
private final List<String> emails;
public Person(String name, int age, List<String> emails) {
this.name = name;
this.age = age;
this.emails = Collections.unmodifiableList(new ArrayList<>(emails));
}
// Getters, equals, hashCode, toString...
// Builder class would be even more code
}
With Immutables.org:
// Just 5 lines!
@Value.Immutable
public interface Person {
String name();
int age();
List<String> emails();
}
Setup and Configuration
1. Maven Dependencies
<dependencies> <dependency> <groupId>org.immutables</groupId> <artifactId>value</artifactId> <version>2.9.3</version> <scope>provided</scope> </dependency> </dependencies>
2. Basic Annotation Processor Setup
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <annotationProcessorPaths> <path> <groupId>org.immutables</groupId> <artifactId>value</artifactId> <version>2.9.3</version> </path> </annotationProcessorPaths> <compilerArgs> <arg>-Amapstruct.defaultComponentModel=spring</arg> </compilerArgs> </configuration> </plugin> </plugins> </build>
Core Immutables Usage Patterns
1. Basic Immutable Objects
import org.immutables.value.Value;
@Value.Immutable
public interface User {
String username();
String email();
int age();
boolean active();
}
// Generated class: ImmutableUser
// Usage:
public class UserService {
public void demonstrateUsage() {
// Builder pattern
User user = ImmutableUser.builder()
.username("john_doe")
.email("[email protected]")
.age(30)
.active(true)
.build();
// Copy with modifications
User updatedUser = ImmutableUser.builder()
.from(user)
.age(31)
.build();
System.out.println(user.username()); // "john_doe"
System.out.println(user.equals(updatedUser)); // false
}
}
2. Collections and Default Values
import java.util.List;
import java.util.Set;
import java.util.Map;
@Value.Immutable
public abstract class Product {
public abstract String sku();
public abstract String name();
public abstract List<String> categories();
public abstract Set<String> tags();
public abstract Map<String, String> attributes();
@Value.Default
public boolean available() {
return true;
}
@Value.Default
public int stock() {
return 0;
}
@Value.Derived
public String displayName() {
return name() + " (" + sku() + ")";
}
}
// Usage example
public class ProductDemo {
public void demonstrate() {
Product product = ImmutableProduct.builder()
.sku("PROD-001")
.name("Laptop")
.addCategories("Electronics", "Computers")
.addTags("new", "featured")
.putAttributes("color", "black")
.putAttributes("weight", "2.5kg")
.stock(50)
.build();
System.out.println(product.displayName()); // "Laptop (PROD-001)"
System.out.println(product.available()); // true (default)
}
}
3. Optional and Nullable Fields
import java.util.Optional;
@Value.Immutable
public interface Customer {
String id();
String name();
Optional<String> phoneNumber();
Optional<String> secondaryEmail();
@Value.Auxiliary
Optional<String> internalNotes();
}
// Usage with Optional fields
public class CustomerService {
public void handleCustomer() {
// Customer with phone number
Customer withPhone = ImmutableCustomer.builder()
.id("CUST-001")
.name("Alice Smith")
.phoneNumber("+1234567890")
.build();
// Customer without phone number
Customer withoutPhone = ImmutableCustomer.builder()
.id("CUST-002")
.name("Bob Johnson")
.build();
// Safe access to optional fields
withPhone.phoneNumber().ifPresent(phone ->
System.out.println("Phone: " + phone));
// Default value for absent optional
String contact = withoutPhone.phoneNumber()
.orElse("No phone provided");
}
}
Advanced Features
1. JSON Serialization with Jackson
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
@Value.Immutable
@JsonSerialize(as = ImmutableOrder.class)
@JsonDeserialize(as = ImmutableOrder.class)
public interface Order {
String orderId();
String customerId();
List<OrderItem> items();
OrderStatus status();
@Value.Immutable
@JsonSerialize(as = ImmutableOrderItem.class)
@JsonDeserialize(as = ImmutableOrderItem.class)
interface OrderItem {
String productId();
int quantity();
double price();
}
enum OrderStatus {
PENDING, CONFIRMED, SHIPPED, DELIVERED
}
}
// JSON Serialization usage
public class OrderService {
private final ObjectMapper mapper = new ObjectMapper();
public void jsonDemo() throws Exception {
Order order = ImmutableOrder.builder()
.orderId("ORD-001")
.customerId("CUST-001")
.addItems(ImmutableOrderItem.builder()
.productId("PROD-001")
.quantity(2)
.price(299.99)
.build())
.status(Order.OrderStatus.PENDING)
.build();
// Serialize to JSON
String json = mapper.writeValueAsString(order);
System.out.println(json);
// Deserialize from JSON
Order deserialized = mapper.readValue(json, Order.class);
System.out.println(deserialized.orderId()); // "ORD-001"
}
}
2. Custom Builder Methods
@Value.Immutable
@Value.Style(strictBuilder = true)
public abstract class BankAccount {
public abstract String accountNumber();
public abstract String owner();
public abstract double balance();
public abstract Currency currency();
// Custom builder method
public static ImmutableBankAccount.Builder builder() {
return ImmutableBankAccount.builder();
}
// Factory method with validation
public static BankAccount create(String accountNumber, String owner,
double initialBalance, Currency currency) {
if (initialBalance < 0) {
throw new IllegalArgumentException("Initial balance cannot be negative");
}
return ImmutableBankAccount.builder()
.accountNumber(accountNumber)
.owner(owner)
.balance(initialBalance)
.currency(currency)
.build();
}
// Instance methods
public BankAccount deposit(double amount) {
if (amount <= 0) {
throw new IllegalArgumentException("Deposit amount must be positive");
}
return ImmutableBankAccount.builder()
.from(this)
.balance(this.balance() + amount)
.build();
}
public BankAccount withdraw(double amount) {
if (amount <= 0) {
throw new IllegalArgumentException("Withdrawal amount must be positive");
}
if (amount > this.balance()) {
throw new IllegalArgumentException("Insufficient funds");
}
return ImmutableBankAccount.builder()
.from(this)
.balance(this.balance() - amount)
.build();
}
}
// Usage with custom methods
public class BankDemo {
public void demonstrate() {
BankAccount account = BankAccount.create("ACC-123", "John Doe", 1000.0, Currency.USD);
BankAccount afterDeposit = account.deposit(500.0);
BankAccount afterWithdrawal = afterDeposit.withdraw(200.0);
System.out.println("Final balance: " + afterWithdrawal.balance()); // 1300.0
}
}
3. Nested Immutable Structures
@Value.Immutable
public abstract class Project {
public abstract String id();
public abstract String name();
public abstract List<Task> tasks();
public abstract Team team();
@Value.Immutable
public abstract static class Task {
public abstract String taskId();
public abstract String description();
public abstract Optional<LocalDate> dueDate();
public abstract TaskStatus status();
public abstract Set<String> assignees();
public enum TaskStatus {
TODO, IN_PROGRESS, REVIEW, DONE
}
}
@Value.Immutable
public abstract static class Team {
public abstract String teamId();
public abstract String name();
public abstract List<TeamMember> members();
}
@Value.Immutable
public abstract static class TeamMember {
public abstract String memberId();
public abstract String name();
public abstract String role();
}
}
// Complex nested builder
public class ProjectManager {
public Project createProject() {
return ImmutableProject.builder()
.id("PROJ-001")
.name("New Website")
.addTasks(ImmutableTask.builder()
.taskId("TASK-001")
.description("Design homepage")
.dueDate(LocalDate.of(2024, 12, 31))
.status(Project.Task.TaskStatus.TODO)
.addAssignees("DES-001")
.build())
.team(ImmutableTeam.builder()
.teamId("TEAM-001")
.name("Web Team")
.addMembers(ImmutableTeamMember.builder()
.memberId("DES-001")
.name("Alice")
.role("Designer")
.build())
.build())
.build();
}
}
Style Customization and Configuration
1. Global Style Configuration
// Maven compiler configuration for global styles <compilerArgs> <arg>-Aimmutables.generated=.*</arg> <arg>-Aimmutables.style=strict</arg> <arg>-Aimmutables.auxiliary=.*</arg> </compilerArgs>
2. Annotation-Based Style Configuration
import org.immutables.value.Value.Style;
// Custom style for different naming conventions
@Style(
typeImmutable = "*", // Generate Immutable* for all types
typeAbstract = "*", // Accept any abstract type
visibility = Style.ImplementationVisibility.PUBLIC,
builder = "new", // Use 'new' instead of 'builder'
build = "create", // Use 'create' instead of 'build'
defaults = @Value.Immutable(builder = false) // Disable builder by default
)
public @interface CustomStyle {}
@CustomStyle
@Value.Immutable
public interface Configuration {
String host();
int port();
boolean sslEnabled();
}
// Usage with custom style
public class ConfigDemo {
public void demonstrate() {
// Now uses 'new' and 'create' instead of 'builder' and 'build'
Configuration config = new ImmutableConfiguration()
.host("localhost")
.port(8080)
.sslEnabled(false)
.create();
}
}
3. Different Styles for Different Use Cases
// Jackson-friendly style
@Style(
typeImmutable = "*",
visibility = Style.ImplementationVisibility.PACKAGE,
overshadowImplementation = true,
builderVisibility = Style.ImplementationVisibility.PACKAGE
)
@interface JacksonStyle {}
// MongoDB-friendly style
@Style(
typeImmutable = "Mongo*",
passAnnotations = { org.mongodb.morphia.annotations.Entity.class }
)
@interface MongoStyle {}
@JacksonStyle
@Value.Immutable
public interface ApiResponse {
boolean success();
String message();
Object data();
}
@MongoStyle
@Value.Immutable
@Entity("users")
public abstract class MongoUser {
@org.mongodb.morphia.annotations.Id
public abstract String id();
public abstract String username();
public abstract String email();
}
Validation and Preconditions
1. Attribute Validation
@Value.Immutable
@Value.Style(strictBuilder = true)
public abstract class ValidatedUser {
@Value.Check
protected void check() {
if (username().length() < 3) {
throw new IllegalStateException("Username must be at least 3 characters");
}
if (age() < 0 || age() > 150) {
throw new IllegalStateException("Age must be between 0 and 150");
}
}
public abstract String username();
public abstract int age();
public abstract List<String> roles();
// Individual attribute validation
@Value.Check
protected void validateRoles() {
if (roles().isEmpty()) {
throw new IllegalStateException("User must have at least one role");
}
}
}
// Usage with validation
public class ValidationDemo {
public void demonstrate() {
try {
ImmutableValidatedUser.builder()
.username("ab") // Too short - will fail
.age(25)
.addRoles("USER")
.build();
} catch (IllegalStateException e) {
System.out.println("Validation failed: " + e.getMessage());
}
}
}
2. Precondition Methods
@Value.Immutable
@Value.Style(strictBuilder = true)
public abstract class InventoryItem {
public abstract String sku();
public abstract String name();
public abstract int quantity();
public abstract double price();
// Precondition methods in builder
public static class Builder extends ImmutableInventoryItem.Builder {
@Override
public InventoryItem build() {
// Custom validation logic
if (quantity < 0) {
throw new IllegalStateException("Quantity cannot be negative");
}
if (price <= 0) {
throw new IllegalStateException("Price must be positive");
}
return super.build();
}
}
}
Integration with Other Libraries
1. Spring Boot Configuration
@Value.Immutable
@JsonSerialize(as = ImmutableAppConfig.class)
@JsonDeserialize(as = ImmutableAppConfig.class)
public interface AppConfig {
String databaseUrl();
String databaseUsername();
String databasePassword();
int serverPort();
boolean debugEnabled();
@Value.Default
default int cacheSize() {
return 1000;
}
}
@Component
@ConfigurationProperties(prefix = "app")
@EnableConfigurationProperties
public class ApplicationConfiguration {
private AppConfig config;
public void setConfig(AppConfig config) {
this.config = config;
}
public AppConfig getConfig() {
return config;
}
}
// application.yml
app:
config:
database-url: "jdbc:postgresql://localhost:5432/mydb"
database-username: "admin"
database-password: "secret"
server-port: 8080
debug-enabled: true
cache-size: 5000
2. JPA Entity Projections
// Immutable projection for JPA queries
@Value.Immutable
public interface UserProjection {
String getUsername();
String getEmail();
LocalDateTime getCreatedAt();
// Static factory method from entity
static UserProjection from(UserEntity entity) {
return ImmutableUserProjection.builder()
.username(entity.getUsername())
.email(entity.getEmail())
.createdAt(entity.getCreatedAt())
.build();
}
}
// JPA Repository usage
@Repository
public interface UserRepository extends JpaRepository<UserEntity, Long> {
@Query("SELECT new package.ImmutableUserProjection(u.username, u.email, u.createdAt) " +
"FROM UserEntity u WHERE u.active = true")
List<UserProjection> findActiveUserProjections();
}
Testing with Immutables
1. Test Data Builders
@Value.Immutable
public interface TestUser {
String username();
String email();
int age();
List<String> permissions();
// Test data builder pattern
class Builder extends ImmutableTestUser.Builder {
public Builder withDefaultValues() {
return this
.username("testuser")
.email("[email protected]")
.age(25)
.addPermissions("READ", "WRITE");
}
public Builder admin() {
return withDefaultValues()
.username("admin")
.addPermissions("ADMIN");
}
}
}
// Usage in tests
public class UserServiceTest {
@Test
public void testUserCreation() {
TestUser user = new TestUser.Builder()
.withDefaultValues()
.username("specific_user")
.build();
assertThat(user.username()).isEqualTo("specific_user");
assertThat(user.permissions()).contains("READ", "WRITE");
}
@Test
public void testAdminUser() {
TestUser admin = new TestUser.Builder()
.admin()
.build();
assertThat(admin.permissions()).contains("ADMIN");
}
}
2. JSON Testing
public class JsonSerializationTest {
private final ObjectMapper mapper = new ObjectMapper();
@Test
public void testSerializationRoundTrip() throws Exception {
TestUser original = ImmutableTestUser.builder()
.username("testuser")
.email("[email protected]")
.age(30)
.addPermissions("READ")
.build();
String json = mapper.writeValueAsString(original);
TestUser deserialized = mapper.readValue(json, TestUser.class);
assertThat(deserialized).isEqualTo(original);
}
}
Performance Considerations
1. Lazy Derived Attributes
@Value.Immutable
public abstract class ExpensiveComputation {
public abstract String input();
@Value.Lazy
public String expensiveResult() {
// This computation is cached after first call
try {
Thread.sleep(1000); // Simulate expensive operation
return input().toUpperCase();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}
}
// Usage
public class PerformanceDemo {
public void demonstrate() {
ExpensiveComputation comp = ImmutableExpensiveComputation.of("hello");
// First call computes and caches
long start1 = System.currentTimeMillis();
String result1 = comp.expensiveResult();
long time1 = System.currentTimeMillis() - start1;
// Second call uses cached value
long start2 = System.currentTimeMillis();
String result2 = comp.expensiveResult();
long time2 = System.currentTimeMillis() - start2;
System.out.println("First call: " + time1 + "ms"); // ~1000ms
System.out.println("Second call: " + time2 + "ms"); // ~0ms
}
}
Best Practices and Pitfalls
1. Do's and Don'ts
// ✅ GOOD: Simple, focused interfaces
@Value.Immutable
public interface GoodExample {
String name();
int value();
Optional<String> description();
}
// ❌ BAD: Too many responsibilities
@Value.Immutable
public interface BadExample {
String name();
int value();
String description();
List<String> tags();
Map<String, String> metadata();
LocalDateTime created();
LocalDateTime updated();
// ... 20 more fields
}
// ✅ GOOD: Use builders for complex objects
@Value.Immutable
public abstract class ComplexButManageable {
public abstract String id();
public abstract Configuration config();
public abstract List<Item> items();
@Value.Immutable
public abstract static class Configuration {
public abstract String host();
public abstract int port();
public abstract boolean ssl();
}
}
// ✅ GOOD: Use default values appropriately
@Value.Immutable
public interface SmartDefaults {
String name();
@Value.Default
default boolean enabled() {
return true;
}
@Value.Default
default int maxRetries() {
return 3;
}
@Value.Default
default Duration timeout() {
return Duration.ofSeconds(30);
}
}
Migration Strategy
1. Gradual Migration from Lombok
// Phase 1: Coexistence
// lombok.config
lombok.anyConstructor.suppressConstructorProperties = true
// Existing Lombok class
@Data
@Builder
@AllArgsConstructor
public class LegacyUser {
private String username;
private String email;
private int age;
}
// New Immutables interface
@Value.Immutable
public interface NewUser {
String username();
String email();
int age();
// Conversion method
static NewUser from(LegacyUser legacy) {
return ImmutableNewUser.builder()
.username(legacy.getUsername())
.email(legacy.getEmail())
.age(legacy.getAge())
.build();
}
LegacyUser toLegacy() {
return LegacyUser.builder()
.username(username())
.email(email())
.age(age())
.build();
}
}
Conclusion
Immutables.org provides significant advantages for Java development:
Key Benefits:
- Reduced Boilerplate: 90% less code for value objects
- Compile-time Safety: All code generation happens at compile time
- Runtime Performance: No reflection overhead
- Rich Feature Set: Builders, JSON, validation, and more
- Framework Integration: Works with Spring, Jackson, JPA, etc.
When to Use:
- Configuration objects
- DTOs and API models
- Value objects in domain-driven design
- Immutable data structures
- Projections and view models
When to Consider Alternatives:
- Extremely simple data holders (record classes in Java 14+)
- Cases requiring runtime bytecode generation
- Projects already heavily invested in other code generation tools
Immutables.org strikes an excellent balance between convenience and control, making it an ideal choice for modern Java applications that value immutability, type safety, and maintainability.