1+ package org .a2aproject .sdk .util ;
2+
3+ import org .jspecify .annotations .Nullable ;
4+
5+ import java .util .ArrayList ;
6+ import java .util .Collections ;
7+ import java .util .HashMap ;
8+ import java .util .List ;
9+ import java .util .Map ;
10+
11+ /**
12+ * Utility methods for creating defensive copies of collection fields.
13+ * <p>
14+ * The helpers make the immutability and null-handling choices explicit at call sites:
15+ * <ul>
16+ * <li>{@code immutable*} methods are intended for record components and return immutable collections.</li>
17+ * <li>{@code nullable*} methods preserve the {@code null} value of optional components.</li>
18+ * <li>{@code *AllowingNulls} methods are intended for JSON-like maps such as metadata,
19+ * params, and headers, where {@code null} values may be valid protocol data.</li>
20+ * <li>{@code mutable*CopyOrEmpty} methods are intended for builders that need mutable copies.</li>
21+ * </ul>
22+ */
23+ public final class CollectionCopies {
24+
25+ private CollectionCopies () {
26+ }
27+
28+ /**
29+ * Creates an immutable defensive copy of a non-null list.
30+ * <p>
31+ * This method uses {@link List#copyOf(java.util.Collection)} and therefore preserves
32+ * its null-handling semantics: null elements are not allowed.
33+ *
34+ * @param list the source list, must not be {@code null}
35+ * @param <E> the element type
36+ * @return an immutable defensive copy
37+ */
38+ public static <E > List <E > immutableList (List <E > list ) {
39+ return List .copyOf (list );
40+ }
41+
42+ /**
43+ * Creates an immutable defensive copy of a nullable list.
44+ * <p>
45+ * If the source list is {@code null}, this method returns {@code null}. Otherwise it
46+ * uses {@link List#copyOf(java.util.Collection)} and therefore does not allow null elements.
47+ *
48+ * @param list the source list, or {@code null}
49+ * @param <E> the element type
50+ * @return {@code null} if the source is {@code null}, otherwise an immutable defensive copy
51+ */
52+ public static <E > @ Nullable List <E > immutableNullableList (@ Nullable List <E > list ) {
53+ return list == null ? null : List .copyOf (list );
54+ }
55+
56+ /**
57+ * Creates an immutable defensive copy of a nullable list, defaulting to an empty immutable list.
58+ * <p>
59+ * This method is intended for fields where a missing list should be normalized to an empty list
60+ * rather than preserving {@code null}. It uses {@link List#copyOf(java.util.Collection)} for
61+ * non-null input and therefore does not allow null elements.
62+ *
63+ * @param list the source list, or {@code null}
64+ * @param <E> the element type
65+ * @return an immutable empty list if the source is {@code null}, otherwise an immutable defensive copy
66+ */
67+ public static <E > List <E > immutableListOrEmpty (@ Nullable List <E > list ) {
68+ return list == null ? List .of () : List .copyOf (list );
69+ }
70+
71+ /**
72+ * Creates an immutable defensive copy of a non-null map.
73+ * <p>
74+ * This method uses {@link Map#copyOf(Map)} and is intended for typed maps where
75+ * null keys and null values are not valid data.
76+ *
77+ * @param map the source map, must not be {@code null}
78+ * @param <K> the key type
79+ * @param <V> the value type
80+ * @return an immutable defensive copy
81+ */
82+ public static <K , V > Map <K , V > immutableMap (Map <K , V > map ) {
83+ return Map .copyOf (map );
84+ }
85+
86+ /**
87+ * Creates an immutable defensive copy of a nullable map.
88+ * <p>
89+ * If the source map is {@code null}, this method returns {@code null}. Otherwise it
90+ * uses {@link Map#copyOf(Map)} and is intended for typed maps where null keys and
91+ * null values are not valid data.
92+ *
93+ * @param map the source map, or {@code null}
94+ * @param <K> the key type
95+ * @param <V> the value type
96+ * @return {@code null} if the source is {@code null}, otherwise an immutable defensive copy
97+ */
98+ public static <K , V > @ Nullable Map <K , V > immutableNullableMap (@ Nullable Map <K , V > map ) {
99+ return map == null ? null : Map .copyOf (map );
100+ }
101+
102+ /**
103+ * Creates an immutable defensive copy of a non-null map while preserving null values.
104+ * <p>
105+ * This method is intended for JSON-like maps such as metadata, params, and headers,
106+ * where null values may be valid protocol data. It intentionally does not use
107+ * {@link Map#copyOf(Map)}, because {@code Map.copyOf} throws {@link NullPointerException}
108+ * when the source map contains null keys or values.
109+ *
110+ * @param map the source map, must not be {@code null}
111+ * @param <K> the key type
112+ * @param <V> the value type
113+ * @return an immutable defensive copy preserving null values
114+ */
115+ public static <K , V > Map <K , V > immutableMapAllowingNulls (Map <K , V > map ) {
116+ return Collections .unmodifiableMap (new HashMap <>(map ));
117+ }
118+
119+ /**
120+ * Creates an immutable defensive copy of a nullable map while preserving null values.
121+ * <p>
122+ * This method is intended for optional JSON-like maps such as metadata, params, and
123+ * headers, where the field itself may be {@code null} and null values inside the map
124+ * may be valid protocol data.
125+ *
126+ * @param map the source map, or {@code null}
127+ * @param <K> the key type
128+ * @param <V> the value type
129+ * @return {@code null} if the source is {@code null}, otherwise an immutable defensive copy
130+ * preserving null values
131+ */
132+ public static <K , V > @ Nullable Map <K , V > immutableNullableMapAllowingNulls (@ Nullable Map <K , V > map ) {
133+ return map == null ? null : Collections .unmodifiableMap (new HashMap <>(map ));
134+ }
135+
136+ /**
137+ * Creates a mutable defensive copy of a nullable list.
138+ * <p>
139+ * This method is intended for builders that need mutable collection state.
140+ *
141+ * @param list the source list, or {@code null}
142+ * @param <E> the element type
143+ * @return a mutable defensive copy, or an empty mutable list if the source is {@code null}
144+ */
145+ public static <E > List <E > mutableListCopyOrEmpty (@ Nullable List <E > list ) {
146+ return list == null ? new ArrayList <>() : new ArrayList <>(list );
147+ }
148+
149+ /**
150+ * Creates a mutable defensive copy of a nullable map.
151+ * <p>
152+ * This method is intended for builders that need mutable collection state.
153+ *
154+ * @param map the source map, or {@code null}
155+ * @param <K> the key type
156+ * @param <V> the value type
157+ * @return a mutable defensive copy, or an empty mutable map if the source is {@code null}
158+ */
159+ public static <K , V > Map <K , V > mutableMapCopyOrEmpty (@ Nullable Map <K , V > map ) {
160+ return map == null ? new HashMap <>() : new HashMap <>(map );
161+ }
162+ }
0 commit comments