feat: add Immutable Object design pattern (#3448)

immutable/README.md

@@ -0,0 +1,18 @@
+# Immutable Object Pattern
+
+## Intent
+Ensure that an object's state cannot be modified 
+after it is created.
+
+## Explanation
+An immutable object is one whose state cannot be 
+changed once created. All fields are final and set 
+only in the constructor.
+
+## When to use
+- When shared objects must not be changed
+- For thread-safe programming
+- When you need predictable behavior
+
+## Example
+HeroStats in a game — once created, stats remain fixed.

immutable/pom.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.iluwatar</groupId>
+        <artifactId>java-design-patterns</artifactId>
+        <version>1.26.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>immutable</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

immutable/src/main/java/com/iluwatar/immutable/ImmutableObject.java

@@ -0,0 +1,50 @@
+package com.iluwatar.immutable;
+import java.util.Objects;
+
+/**
+ * Immutable Object pattern.
+ * Once created, the object state cannot be changed.
+ */
+public final class ImmutableObject {
+
+    private final String name;
+    private final int age;
+    private final String email;
+
+    public ImmutableObject(
+            final String name,
+            final int age,
+            final String email) {
+    	this.name = Objects.requireNonNull(name, "name cannot be null");
+        this.age = age;
+        this.email = Objects.requireNonNull(email, "email cannot be null");
+    }
+
+    public String getName() { return name; }
+    public int getAge() { return age; }
+    public String getEmail() { return email; }
+
+    @Override
+    public String toString() {
+        return "ImmutableObject{"
+            + "name='" + name + '\''
+            + ", age=" + age
+            + ", email='" + email + '\''
+            + '}';
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof ImmutableObject)) return false;
+        ImmutableObject that = (ImmutableObject) o;
+        return age == that.age
+            && Objects.equals(name, that.name)
+            && Objects.equals(email, that.email);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(name, age, email);
+    }
+}

immutable/src/test/java/com/iluwatar/immutable/ImmutableObjectTest.java

@@ -0,0 +1,52 @@
+package com.iluwatar.immutable;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+class ImmutableObjectTest {
+
+    @Test
+    void testObjectCreation() {
+        ImmutableObject obj = 
+            new ImmutableObject("Prashant", 22, "p@gmail.com");
+
+        assertEquals("Prashant", obj.getName());
+        assertEquals(22, obj.getAge());
+        assertEquals("p@gmail.com", obj.getEmail());
+    }
+
+    @Test
+    void testToString() {
+        ImmutableObject obj = 
+            new ImmutableObject("Prashant", 22, "p@gmail.com");
+
+        assertTrue(obj.toString().contains("Prashant"));
+    }
+
+    @Test
+    void testImmutability() {
+        ImmutableObject obj1 = 
+            new ImmutableObject("A", 1, "a@gmail.com");
+        ImmutableObject obj2 = 
+            new ImmutableObject("A", 1, "a@gmail.com");
+
+        assertNotSame(obj1, obj2);
+    }
+
+    @Test
+    void testEquality() {
+        ImmutableObject obj1 = 
+            new ImmutableObject("A", 1, "a@gmail.com");
+        ImmutableObject obj2 = 
+            new ImmutableObject("A", 1, "a@gmail.com");
+
+        assertEquals(obj1, obj2);
+    }
+
+    @Test
+    void testNullName() {
+        assertThrows(NullPointerException.class, () -> {
+            new ImmutableObject(null, 1, "a@gmail.com");
+        });
+    }
+}