Skip to content

Commit d478368

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

2 files changed

Lines changed: 170 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: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
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 used by spec records.
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 record components.</li>
18+
* <li>{@code *AllowingNulls} methods are intended for JSON-like maps such as metadata,
19+
* params, and headers, where {@code null} keys or 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+
final class SpecCollections {
24+
25+
private SpecCollections() {
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+
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+
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+
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+
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+
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 keys
104+
* and null values.
105+
* <p>
106+
* This method is intended for JSON-like maps such as metadata, params, and headers,
107+
* where null values may be valid protocol data. It intentionally does not use
108+
* {@link Map#copyOf(Map)}, because {@code Map.copyOf} throws {@link NullPointerException}
109+
* when the source map contains null keys or values.
110+
*
111+
* @param map the source map, must not be {@code null}
112+
* @param <K> the key type
113+
* @param <V> the value type
114+
* @return an immutable defensive copy preserving null keys and values
115+
*/
116+
static <K, V> Map<K, V> immutableMapAllowingNulls(Map<K, V> map) {
117+
return Collections.unmodifiableMap(new HashMap<>(map));
118+
}
119+
120+
/**
121+
* Creates an immutable defensive copy of a nullable map while preserving null keys
122+
* and null values.
123+
* <p>
124+
* This method is intended for optional JSON-like maps such as metadata, params, and
125+
* headers, where the field itself may be {@code null} and null values inside the map
126+
* may be valid protocol data.
127+
*
128+
* @param map the source map, or {@code null}
129+
* @param <K> the key type
130+
* @param <V> the value type
131+
* @return {@code null} if the source is {@code null}, otherwise an immutable defensive copy
132+
* preserving null keys and values
133+
*/
134+
static <K, V> @Nullable Map<K, V> immutableNullableMapAllowingNulls(@Nullable Map<K, V> map) {
135+
return map == null ? null : Collections.unmodifiableMap(new HashMap<>(map));
136+
}
137+
138+
/**
139+
* Creates a mutable defensive copy of a nullable list.
140+
* <p>
141+
* This method is intended for builders that need mutable collection state.
142+
*
143+
* @param list the source list, or {@code null}
144+
* @param <E> the element type
145+
* @return a mutable defensive copy, or an empty mutable list if the source is {@code null}
146+
*/
147+
static <E> List<E> mutableListCopyOrEmpty(@Nullable List<E> list) {
148+
return list == null ? new ArrayList<>() : new ArrayList<>(list);
149+
}
150+
151+
/**
152+
* Creates a mutable defensive copy of a nullable map.
153+
* <p>
154+
* This method is intended for builders that need mutable collection state.
155+
*
156+
* @param map the source map, or {@code null}
157+
* @param <K> the key type
158+
* @param <V> the value type
159+
* @return a mutable defensive copy, or an empty mutable map if the source is {@code null}
160+
*/
161+
static <K, V> Map<K, V> mutableMapCopyOrEmpty(@Nullable Map<K, V> map) {
162+
return map == null ? new HashMap<>() : new HashMap<>(map);
163+
}
164+
}

0 commit comments

Comments
 (0)