Package org.apache.juneau.commons.collections

Class ControlledArrayList<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractList<E>
java.util.ArrayList<E>
org.apache.juneau.commons.collections.ControlledArrayList<E>
Type Parameters:
E - The element type.
All Implemented Interfaces:
Serializable, Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess
Direct Known Subclasses:
HeaderList, PartList
public class ControlledArrayList<E> extends ArrayList<E>
An ArrayList that allows you to control whether it's read-only via a constructor parameter.

This class provides a unique capability: it can appear as an unmodifiable list to external code (via the standard List interface methods) while still allowing internal code to modify it through special "override" methods. This is useful when you need to pass a list to code that should not modify it, but you still need to modify it internally.

Features:
  • Controlled Mutability: Can be configured as modifiable or unmodifiable at construction time
  • Override Methods: Special methods (e.g., overrideAdd(Object)) bypass the unmodifiable restriction
  • Standard List Interface: Implements all standard List methods with proper unmodifiable enforcement
  • Iterator Protection: Iterators returned from unmodifiable lists prevent modification operations
  • Dynamic Control: Can be made unmodifiable after construction via setUnmodifiable()
Use Cases:
  • Passing a list to external code that should not modify it, while maintaining internal modification capability
  • Building a list internally and then "freezing" it before exposing it to clients
  • Creating a list that appears read-only to consumers but can be modified by trusted internal code
  • Implementing defensive copying patterns where the original list needs to remain mutable internally
Usage:

// Create a list that appears unmodifiable to external code ControlledArrayList<String> list = new ControlledArrayList<>(true); // Internal code can still modify using override methods list.overrideAdd("item1"); list.overrideAdd("item2"); // External code sees it as unmodifiable list.add("item3"); // Throws UnsupportedOperationException // Pass to external code safely processList(list); // External code cannot modify it // But internal code can still modify list.overrideAdd("item3"); // Works!

Override Methods:

The "override" methods (e.g., overrideAdd(Object), overrideRemove(int)) bypass the unmodifiable restriction and allow modification regardless of the list's modifiable state. These methods are intended for use by trusted internal code that needs to modify the list even when it's marked as unmodifiable.

// Create unmodifiable list ControlledArrayList<String> list = new ControlledArrayList<>(true); // Standard methods throw exceptions list.add("x"); // UnsupportedOperationException list.remove(0); // UnsupportedOperationException // Override methods work list.overrideAdd("x"); // OK list.overrideRemove(0); // OK

Iterator Behavior:

When the list is unmodifiable, iterators returned by iterator() and listIterator() are read-only. Attempting to call Iterator.remove() or ListIterator.set(Object) on these iterators will throw UnsupportedOperationException. However, the override methods can still be used to modify the list.

Thread Safety:

This class is not thread-safe. If multiple threads access a ControlledArrayList concurrently, and at least one thread modifies the list structurally, it must be synchronized externally. The unmodifiable flag does not provide thread-safety; it only controls whether standard List interface methods can modify the list.

Example - Building and Freezing:

// Build a list internally ControlledArrayList<String> config = new ControlledArrayList<>(false); config.add("setting1"); config.add("setting2"); // Freeze it before exposing config.setUnmodifiable(); // Now safe to expose - external code cannot modify return config;

See Also:
See Also:

  • Constructor Details

    • ControlledArrayList

      public ControlledArrayList(boolean unmodifiable)
      Constructor.

      Creates an empty list with the specified modifiability setting.

      Example:

      // Create an empty unmodifiable list ControlledArrayList<String> list = new ControlledArrayList<>(true); // Create an empty modifiable list ControlledArrayList<String> list2 = new ControlledArrayList<>(false);

      Parameters:
      unmodifiable - If true, this list cannot be modified through normal list operation methods on the List interface. Use override methods to modify when unmodifiable.

    • ControlledArrayList

      public ControlledArrayList(boolean unmodifiable, List<? extends E> list)
      Constructor.

      Creates a list with the specified initial contents and modifiability setting.

      Example:

      // Create an unmodifiable list with initial contents List<String> initial = List.of("a", "b", "c"); ControlledArrayList<String> list = new ControlledArrayList<>(true, initial); // Standard methods throw exceptions list.add("d"); // UnsupportedOperationException

      Parameters:
      unmodifiable - If true, this list cannot be modified through normal list operation methods on the List interface. Use override methods to modify when unmodifiable.
      list - The initial contents of this list. Must not be null.

  • Method Details