Skip to content

Commit 48d517f

Browse files
committed
feat: harden spec immutability
1 parent 19693d3 commit 48d517f

2 files changed

Lines changed: 168 additions & 2 deletions

File tree

‎spec/src/main/java/org/a2aproject/sdk/spec/AgentCard.java‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
package org.a2aproject.sdk.spec;
22

3-
import java.util.*;
4-
53
import org.a2aproject.sdk.util.Assert;
64
import org.jspecify.annotations.Nullable;
75

6+
import java.util.ArrayList;
7+
import java.util.Collections;
8+
import java.util.HashMap;
9+
import java.util.List;
10+
import java.util.Map;
11+
812
/**
913
* The AgentCard is a self-describing manifest for an agent in the A2A Protocol.
1014
* <p>
Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
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

Comments
 (0)