@@ -100,37 +100,39 @@ public static <K, V> Map<K, V> immutableMap(Map<K, V> map) {
100100 }
101101
102102 /**
103- * Creates an immutable defensive copy of a non-null map while preserving null values.
103+ * Creates an unmodifiable shallow defensive copy of a non-null map while preserving null values.
104104 * <p>
105105 * This method is intended for JSON-like maps such as metadata, params, and headers,
106106 * where null values may be valid protocol data. It intentionally does not use
107107 * {@link Map#copyOf(Map)}, because {@code Map.copyOf} throws {@link NullPointerException}
108108 * when the source map contains null keys or values.
109+ * <p>
110+ * The returned map cannot be structurally modified, but this method does not deep-copy
111+ * mutable keys or values.
109112 *
110113 * @param map the source map, must not be {@code null}
111114 * @param <K> the key type
112115 * @param <V> the value type
113- * @return an immutable defensive copy preserving null values
116+ * @return an unmodifiable shallow copy preserving null values
114117 */
115- public static <K , V > Map <K , V > immutableMapAllowingNulls (Map <K , V > map ) {
118+ public static <K , V > Map <K , V > unmodifiableShallowMap (Map <K , V > map ) {
116119 return Collections .unmodifiableMap (new HashMap <>(map ));
117120 }
118121
119122 /**
120- * Creates an immutable defensive copy of a nullable map while preserving null values.
123+ * Creates an unmodifiable shallow defensive copy of a nullable map while preserving null values.
121124 * <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+ * If the source map is {@code null}, this method returns {@code null}. Otherwise it behaves like
126+ * {@link #unmodifiableShallowMap(Map)}.
125127 *
126128 * @param map the source map, or {@code null}
127129 * @param <K> the key type
128130 * @param <V> the value type
129- * @return {@code null} if the source is {@code null}, otherwise an immutable defensive copy
131+ * @return {@code null} if the source is {@code null}, otherwise an unmodifiable shallow copy
130132 * preserving null values
131133 */
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+ public static <K , V > @ Nullable Map <K , V > unmodifiableNullableShallowMap (@ Nullable Map <K , V > map ) {
135+ return map == null ? null : unmodifiableShallowMap ( map );
134136 }
135137
136138 /**
0 commit comments