Add Immutable static helper

Author: hjohn

common-collection/src/main/java/org/int4/common/collection/Immutable.java

@@ -0,0 +1,157 @@
+package org.int4.common.collection;
+
+import java.util.AbstractList;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+import java.util.ListIterator;
+import java.util.Objects;
+import java.util.RandomAccess;
+
+/**
+ * Utility for creating immutable representations of common collection types.
+ * <p>
+ * This class provides factory methods that accept existing mutable or immutable
+ * collections and return a logically immutable view of their contents.
+ * <p>
+ * Where possible, known immutable implementations are detected and returned
+ * without copying. Otherwise, a defensive copy is created to ensure isolation
+ * from subsequent external modifications.
+ * <p>
+ * The immutability guarantee applies to the returned collection interface:
+ * structural modification operations are not supported and will result in
+ * {@link UnsupportedOperationException}.
+ * <p>
+ * Null elements are preserved unless otherwise specified by a particular method.
+ */
+public abstract class Immutable {
+
+  /**
+   * Returns an immutable representation of the given list.
+   * <p>
+   * If the provided list is already a known immutable implementation,
+   * it is returned as-is without copying.
+   * <p>
+   * Otherwise, a defensive copy of the input is created and wrapped in an
+   * immutable view to prevent external mutation.
+   * <p>
+   * The returned list does not permit structural modification operations
+   * and will throw {@link UnsupportedOperationException} if such methods are
+   * invoked.
+   * <p>
+   * Null elements are preserved.
+   *
+   * @param <T> element type
+   * @param list the source list, must not be {@code null}
+   * @return an immutable list backed by a defensive copy, or the original list
+   *   if it is already immutable, never {@code null}
+   * @throws NullPointerException if {@code list} is {@code null}
+   */
+  public static <T> List<T> of(List<T> list) {
+    Objects.requireNonNull(list, "list");
+
+    if(isKnownImmutable(list)) {
+      return list;
+    }
+
+    return list instanceof RandomAccess
+      ? new RandomAccessImmutableList<>(Collections.unmodifiableList(new ArrayList<>(list)))
+      : new ImmutableList<>(Collections.unmodifiableList(new ArrayList<>(list)));
+  }
+
+  private static boolean isKnownImmutable(List<?> list) {
+    return list instanceof RandomAccessImmutableList<?>
+      || list instanceof ImmutableList<?>
+      || list.getClass().getName().startsWith("java.util.ImmutableCollections$");
+  }
+
+  private static final class RandomAccessImmutableList<T> extends AbstractList<T> implements RandomAccess {
+    private final List<T> delegate;
+
+    private RandomAccessImmutableList(List<T> delegate) {
+      this.delegate = delegate;
+    }
+
+    @Override
+    public T get(int index) {
+      return delegate.get(index);
+    }
+
+    @Override
+    public int size() {
+      return delegate.size();
+    }
+
+    @Override
+    public boolean contains(Object o) {
+      return delegate.contains(o);
+    }
+
+    @Override
+    public int indexOf(Object o) {
+      return delegate.indexOf(o);
+    }
+
+    @Override
+    public int lastIndexOf(Object o) {
+      return delegate.lastIndexOf(o);
+    }
+
+    @Override
+    public Iterator<T> iterator() {
+      return delegate.iterator();
+    }
+
+    @Override
+    public ListIterator<T> listIterator(int index) {
+      return delegate.listIterator(index);
+    }
+  }
+
+  private static final class ImmutableList<T> extends AbstractList<T> {
+    private final List<T> delegate;
+
+    private ImmutableList(List<T> delegate) {
+      this.delegate = delegate;
+    }
+
+    @Override
+    public T get(int index) {
+      return delegate.get(index);
+    }
+
+    @Override
+    public int size() {
+      return delegate.size();
+    }
+
+    @Override
+    public boolean contains(Object o) {
+      return delegate.contains(o);
+    }
+
+    @Override
+    public int indexOf(Object o) {
+      return delegate.indexOf(o);
+    }
+
+    @Override
+    public int lastIndexOf(Object o) {
+      return delegate.lastIndexOf(o);
+    }
+
+    @Override
+    public Iterator<T> iterator() {
+      return delegate.iterator();
+    }
+
+    @Override
+    public ListIterator<T> listIterator(int index) {
+      return delegate.listIterator(index);
+    }
+  }
+
+  private Immutable() {
+  }
+}

common-collection/src/test/java/org/int4/common/collection/ImmutableTest.java

@@ -0,0 +1,122 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 John Hendrikx
+ *
+ * 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 org.int4.common.collection;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.RandomAccess;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class ImmutableTest {
+
+  @Test
+  void shouldThrowExceptionWhenListIsNull() {
+    assertThatThrownBy(() -> Immutable.of(null))
+      .isExactlyInstanceOf(NullPointerException.class)
+      .hasMessage("list");
+  }
+
+  @Test
+  void shouldCreateImmutableCopyOfMutableList() {
+    List<String> mutableList = new ArrayList<>(Arrays.asList("a", "b", "c"));
+    List<String> immutableList = Immutable.of(mutableList);
+
+    assertThat(immutableList).containsExactly("a", "b", "c");
+
+    mutableList.add("d");
+
+    assertThat(immutableList).containsExactly("a", "b", "c");
+    assertThat(immutableList).hasSize(3);
+  }
+
+  @Test
+  void shouldNotAllowModifications() {
+    List<String> immutableList = Immutable.of(Arrays.asList("a", "b"));
+
+    assertThatThrownBy(() -> immutableList.add("c")).isExactlyInstanceOf(UnsupportedOperationException.class);
+    assertThatThrownBy(() -> immutableList.remove(0)).isExactlyInstanceOf(UnsupportedOperationException.class);
+    assertThatThrownBy(() -> immutableList.set(0, "z")).isExactlyInstanceOf(UnsupportedOperationException.class);
+    assertThatThrownBy(() -> immutableList.clear()).isExactlyInstanceOf(UnsupportedOperationException.class);
+  }
+
+  @Test
+  void shouldReturnSameInstanceIfAlreadyImmutable() {
+    List<String> original = List.of("a", "b");
+    List<String> immutable = Immutable.of(original);
+
+    assertThat(immutable).isSameAs(original);
+
+    List<String> doubleImmutable = Immutable.of(immutable);
+
+    assertThat(doubleImmutable).isSameAs(immutable);
+  }
+
+  @Test
+  void shouldPreserveRandomAccess() {
+    List<String> arrayList = new ArrayList<>(Arrays.asList("a", "b"));
+    List<String> immutableArrayList = Immutable.of(arrayList);
+
+    assertThat(immutableArrayList).isInstanceOf(RandomAccess.class);
+    assertThat(immutableArrayList.getClass().getSimpleName()).contains("RandomAccess");
+
+    List<String> linkedList = new LinkedList<>(Arrays.asList("a", "b"));
+    List<String> immutableLinkedList = Immutable.of(linkedList);
+
+    assertThat(immutableLinkedList).isNotInstanceOf(RandomAccess.class);
+    assertThat(immutableLinkedList.getClass().getSimpleName()).doesNotContain("RandomAccess");
+  }
+
+  @Test
+  void shouldPreserveNulls() {
+    List<String> listWithNulls = Arrays.asList("a", null, "c");
+    List<String> immutable = Immutable.of(listWithNulls);
+
+    assertThat(immutable).containsExactly("a", null, "c");
+    assertThat(immutable.get(1)).isNull();
+    assertThat(immutable.contains(null)).isTrue();
+    assertThat(immutable.indexOf(null)).isEqualTo(1);
+    assertThat(immutable.lastIndexOf(null)).isEqualTo(1);
+  }
+
+  @Test
+  void shouldSupportBasicListOperations() {
+    List<String> list = Immutable.of(Arrays.asList("a", "b", "a"));
+
+    assertThat(list.get(0)).isEqualTo("a");
+    assertThat(list.size()).isEqualTo(3);
+    assertThat(list.contains("b")).isTrue();
+    assertThat(list.contains("c")).isFalse();
+    assertThat(list.indexOf("a")).isEqualTo(0);
+    assertThat(list.lastIndexOf("a")).isEqualTo(2);
+    assertThat(list.iterator()).toIterable().containsExactly("a", "b", "a");
+    assertThat(list.listIterator(1)).toIterable().containsExactly("b", "a");
+  }
+}