feat: implement Immutable pattern (Fixes #3448)

immutable/README.md

@@ -0,0 +1,133 @@
+---
+title: "Immutable Pattern in Java: Building Thread-Safe Objects"
+shortTitle: Immutable
+description: "Learn the Immutable pattern in Java with real-world examples, class diagrams, and tutorials. Understand how to create objects that cannot be modified after construction."
+category: Idiom
+language: en
+tag:
+  - Immutability
+  - Thread safety
+  - Concurrency
+  - Object composition
+---
+
+## Also known as
+
+Value Object (when applied strictly to small domain values)
+
+## Intent of Immutable Design Pattern
+
+Ensure that an object's state cannot be changed after it is constructed, making it inherently thread-safe and easier to reason about.
+
+## Detailed Explanation of Immutable Pattern with Real-World Examples
+
+Real-world example
+
+> A birth certificate is a perfect real-world analogy for the Immutable pattern. Once issued, a birth certificate records a person's name, date of birth, and place of birth permanently. You cannot alter the certificate itself; if a legal correction is needed, a new certificate is issued. The original document remains unchanged, guaranteeing that every copy handed to a bank, school, or government office reflects exactly the same facts.
+
+In plain words
+
+> An immutable object is one whose state is fixed at construction time and can never change. Instead of modifying an existing object, you create a new one with the desired state.
+
+Wikipedia says
+
+> In object-oriented and functional programming, an immutable object (unchangeable object) is an object whose state cannot be modified after it is created. This is in contrast to a mutable object (changeable object), which can be modified after it is created.
+
+Class diagram
+
+![Immutable class diagram](./etc/immutable.urm.puml)
+
+## Programmatic Example of Immutable Pattern in Java
+
+The core of the pattern is `ImmutableUser`. All fields are `final`, the mutable `roles` list is defensively copied via `List.copyOf`, and "mutation" is expressed by returning a new instance.
+
+```java
+public final class ImmutableUser {
+
+  private final String name;
+  private final int age;
+  private final List<String> roles;
+
+  public ImmutableUser(String name, int age, List<String> roles) {
+    this.name = name;
+    this.age = age;
+    this.roles = List.copyOf(roles);
+  }
+
+  public String getName() { return name; }
+  public int getAge()     { return age; }
+  public List<String> getRoles() { return roles; }
+
+  public ImmutableUser withAge(int newAge) {
+    return new ImmutableUser(this.name, newAge, this.roles);
+  }
+}
+```
+
+`App` demonstrates the pattern in action:
+
+```java
+var alice = new ImmutableUser("Alice", 30, List.of("admin", "user"));
+LOGGER.info("Original user: {}", alice);
+
+var olderAlice = alice.withAge(31);
+LOGGER.info("Updated user (new object): {}", olderAlice);
+LOGGER.info("Original is unchanged: {}", alice);
+
+var mutableRoles = new ArrayList<>(List.of("viewer"));
+var bob = new ImmutableUser("Bob", 25, mutableRoles);
+mutableRoles.add("editor");
+LOGGER.info("Bob's roles (unchanged despite external list mutation): {}", bob.getRoles());
+```
+
+Running the example produces output similar to:
+
+```
+INFO  com.iluwatar.immutable.App - Original user: ImmutableUser{name='Alice', age=30, roles=[admin, user]}
+INFO  com.iluwatar.immutable.App - Updated user (new object): ImmutableUser{name='Alice', age=31, roles=[admin, user]}
+INFO  com.iluwatar.immutable.App - Original is unchanged: ImmutableUser{name='Alice', age=30, roles=[admin, user]}
+INFO  com.iluwatar.immutable.App - Bob's roles (unchanged despite external list mutation): [viewer]
+```
+
+## When to Use the Immutable Pattern in Java
+
+* When objects are shared across threads and synchronization overhead is undesirable.
+* When you need objects to be used safely as map keys or in sets (consistent `hashCode`).
+* When you want to model value types such as money, dates, or coordinates.
+* When defensive programming is critical and you must prevent accidental state corruption.
+
+## Real-World Applications of Immutable Pattern in Java
+
+* `java.lang.String` — the quintessential immutable class in the JDK.
+* `java.time.LocalDate`, `LocalDateTime` — immutable date/time representations.
+* `java.math.BigDecimal`, `BigInteger` — immutable numeric types.
+* Record classes introduced in Java 16 — compiler-generated immutable data carriers.
+
+## Benefits and Trade-offs of Immutable Pattern
+
+Benefits:
+
+* **Thread safety**: No synchronization needed; immutable objects can be shared freely across threads.
+* **Simplicity**: Absence of state changes eliminates a whole category of bugs.
+* **Safe sharing**: Can be freely passed to untrusted code without defensive copying at call sites.
+* **Cache-friendly**: Immutable objects can be cached, interned, or pre-computed without risk.
+
+Trade-offs:
+
+* **Object creation overhead**: Every logical "update" allocates a new object, which may pressure the garbage collector in hot paths.
+* **Verbose construction**: Complex objects often require a Builder to avoid unwieldy constructors.
+* **Not always applicable**: Objects that model inherently stateful entities (e.g., a network connection) cannot reasonably be immutable.
+
+## Related Java Design Patterns
+
+* [Value Object](https://java-design-patterns.com/patterns/value-object/): Overlapping concept; value objects are typically immutable and compared by value rather than identity.
+* [Builder](https://java-design-patterns.com/patterns/builder/): Commonly paired with Immutable to construct complex objects step-by-step before freezing them.
+* [Prototype](https://java-design-patterns.com/patterns/prototype/): Cloning a mutable object is an alternative to immutability when shared state must occasionally change.
+* [Flyweight](https://java-design-patterns.com/patterns/flyweight/): Leverages immutability to safely share fine-grained objects across many contexts.
+
+## References and Credits
+
+* [Effective Java, 3rd Edition — Item 17: Minimize Mutability](https://amzn.to/3JIYJoL)
+* [Java Concurrency in Practice](https://amzn.to/3vXyUEh)
+* [Clean Code: A Handbook of Agile Software Craftsmanship](https://amzn.to/3JIYJoL)
+* [Wikipedia — Immutable object](https://en.wikipedia.org/wiki/Immutable_object)

immutable/etc/immutable.urm.puml

@@ -0,0 +1,21 @@
+@startuml
+package com.iluwatar.immutable {
+  class App {
+    - LOGGER : Logger {static}
+    + App()
+    + main(args : String[]) {static}
+  }
+  class ImmutableUser {
+    - name : String {final}
+    - age : int {final}
+    - roles : List<String> {final}
+    + ImmutableUser(name : String, age : int, roles : List<String>)
+    + getName() : String
+    + getAge() : int
+    + getRoles() : List<String>
+    + withAge(newAge : int) : ImmutableUser
+    + toString() : String
+  }
+}
+App ..> ImmutableUser : creates
+@enduml

immutable/pom.xml

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt).
+
+    The MIT License
+    Copyright © 2014-2022 Ilkka Seppälä
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+
+-->
+<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.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>ch.qos.logback</groupId>
+      <artifactId>logback-classic</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <executions>
+          <execution>
+            <configuration>
+              <archive>
+                <manifest>
+                  <mainClass>com.iluwatar.immutable.App</mainClass>
+                </manifest>
+              </archive>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>

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

@@ -0,0 +1,61 @@
+/*
+ * This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt).
+ *
+ * The MIT License
+ * Copyright © 2014-2022 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.immutable;
+
+import java.util.List;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * The Immutable pattern ensures that an object's state cannot be changed after construction.
+ *
+ * <p>In this example, {@link ImmutableUser} demonstrates the pattern: all fields are final, the
+ * mutable {@code roles} list is defensively copied, and any state change produces a brand-new
+ * instance via {@link ImmutableUser#withAge(int)}.
+ */
+public class App {
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(App.class);
+
+  /**
+   * Program entry point.
+   *
+   * @param args command line args
+   */
+  public static void main(String[] args) {
+    var alice = new ImmutableUser("Alice", 30, List.of("admin", "user"));
+    LOGGER.info("Original user: {}", alice);
+
+    var olderAlice = alice.withAge(31);
+    LOGGER.info("Updated user (new object): {}", olderAlice);
+    LOGGER.info("Original is unchanged: {}", alice);
+
+    // Demonstrate defensive copy: mutating the source list does not affect alice
+    var mutableRoles = new java.util.ArrayList<>(List.of("viewer"));
+    var bob = new ImmutableUser("Bob", 25, mutableRoles);
+    mutableRoles.add("editor");
+    LOGGER.info("Bob's roles (unchanged despite external list mutation): {}", bob.getRoles());
+  }
+}