Package org.a2aproject.sdk.spec.util

Class CollectionCopies

java.lang.Object
org.a2aproject.sdk.spec.util.CollectionCopies
public final class CollectionCopies extends Object
Utility methods for creating defensive copies of collection fields.

The helpers make the immutability and null-handling choices explicit at call sites:

  • immutable* methods are intended for record components and return immutable collections.
  • nullable* methods preserve the null value of optional components.
  • *AllowingNulls methods are intended for JSON-like maps such as metadata, params, and headers, where null values may be valid protocol data.
  • mutable*CopyOrEmpty methods are intended for builders that need mutable copies.

  • Method Details

    • immutableList

      public static <E> List<E> immutableList(List<E> list)
      Creates an immutable defensive copy of a non-null list.

      This method uses List.copyOf(java.util.Collection) and therefore preserves its null-handling semantics: null elements are not allowed.

      Type Parameters:
      E - the element type
      Parameters:
      list - the source list, must not be null
      Returns:
      an immutable defensive copy

    • immutableNullableList

      public static <E> @Nullable List<E> immutableNullableList(@Nullable List<E> list)
      Creates an immutable defensive copy of a nullable list.

      If the source list is null, this method returns null. Otherwise it uses List.copyOf(java.util.Collection) and therefore does not allow null elements.

      Type Parameters:
      E - the element type
      Parameters:
      list - the source list, or null
      Returns:
      null if the source is null, otherwise an immutable defensive copy

    • immutableListOrEmpty

      public static <E> List<E> immutableListOrEmpty(@Nullable List<E> list)
      Creates an immutable defensive copy of a nullable list, defaulting to an empty immutable list.

      This method is intended for fields where a missing list should be normalized to an empty list rather than preserving null. It uses List.copyOf(java.util.Collection) for non-null input and therefore does not allow null elements.

      Type Parameters:
      E - the element type
      Parameters:
      list - the source list, or null
      Returns:
      an immutable empty list if the source is null, otherwise an immutable defensive copy

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(Map<K,V> map)
      Creates an immutable defensive copy of a non-null map.

      This method uses Map.copyOf(Map) and is intended for typed maps where null keys and null values are not valid data.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the source map, must not be null
      Returns:
      an immutable defensive copy

    • immutableNullableMap

      public static <K, V> @Nullable Map<K,V> immutableNullableMap(@Nullable Map<K,V> map)
      Creates an immutable defensive copy of a nullable map.

      If the source map is null, this method returns null. Otherwise it uses Map.copyOf(Map) and is intended for typed maps where null keys and null values are not valid data.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the source map, or null
      Returns:
      null if the source is null, otherwise an immutable defensive copy

    • unmodifiableShallowMap

      public static <K, V> Map<K,V> unmodifiableShallowMap(Map<K,V> map)
      Creates an unmodifiable shallow defensive copy of a non-null map while preserving null values.

      This method is intended for JSON-like maps such as metadata, params, and headers, where null values may be valid protocol data. It intentionally does not use Map.copyOf(Map), because Map.copyOf throws NullPointerException when the source map contains null keys or values.

      The returned map cannot be structurally modified, but this method does not deep-copy mutable keys or values.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the source map, must not be null
      Returns:
      an unmodifiable shallow copy preserving null values

    • unmodifiableNullableShallowMap

      public static <K, V> @Nullable Map<K,V> unmodifiableNullableShallowMap(@Nullable Map<K,V> map)
      Creates an unmodifiable shallow defensive copy of a nullable map while preserving null values.

      If the source map is null, this method returns null. Otherwise it behaves like unmodifiableShallowMap(Map).

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the source map, or null
      Returns:
      null if the source is null, otherwise an unmodifiable shallow copy preserving null values

    • mutableListCopyOrEmpty

      public static <E> List<E> mutableListCopyOrEmpty(@Nullable List<E> list)
      Creates a mutable defensive copy of a nullable list.

      This method is intended for builders that need mutable collection state.

      Type Parameters:
      E - the element type
      Parameters:
      list - the source list, or null
      Returns:
      a mutable defensive copy, or an empty mutable list if the source is null

    • mutableMapCopyOrEmpty

      public static <K, V> Map<K,V> mutableMapCopyOrEmpty(@Nullable Map<K,V> map)
      Creates a mutable defensive copy of a nullable map.

      This method is intended for builders that need mutable collection state.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the source map, or null
      Returns:
      a mutable defensive copy, or an empty mutable map if the source is null