Document HttpHeaders#toSingleValueMap() case-sensitive behavior

[OrangeDog]

The map returned by HttpHeaders.toSingleValueMap() is not case-insensitive.

This copy also ensures that collection-iterating methods like entrySet() are case-insensitive.

var response = restTemplate.getForEntity(uri, String.class);
assertTrue(response.getHeaders().containsHeader("date");  // passes
assertTrue(response.getHeaders().containsHeader("Date");  // passes
assertTrue(response.getHeaders().toSingleValueMap().keySet().contains("date");  // passes
assertTrue(response.getHeaders().toSingleValueMap().keySet().contains("Date");  // fails

Which case they're been normalised to depends on the request factory.

Tested with Spring Framework 7.0.2 (via Boot 4.0.1).

[bclozel]

Have you seen #36056 ?

Can you try with snapshots and report back please?

[OrangeDog]

I did not see that, but toSingleValueMap() is not returning a LinkedCaseInsensitiveMap in the first place:

System.out.println(restTemplate.getForEntity("/", String.class).getHeaders().toSingleValueMap().getClass())
// class java.util.LinkedHashMap

[TerryTaoYY]

I think the behavior is best explained as a documentation mismatch.

HttpHeaders itself is designed to treat header names case-insensitively, as containsHeader("date") / containsHeader("Date") assertions demonstrate.
However, toSingleValueMap() returns a detached Map<String,String> copy of first values, and in the example it’s a plain LinkedHashMap, so the keys in that map are whatever casing the underlying client/request factory happened to store (date). From there, toSingleValueMap().keySet().contains("Date") is not a reliable way to test header presence, because it depends on the stored casing in the returned copy.

If need case-insensitive membership checks, I’d suggest sticking with the HttpHeaders API,

• response.getHeaders().containsHeader("Date") , or
• response.getHeaders().headerNames() / headerSet() if want a case-insensitive view for iteration and membership checks.

If specifically need a single-value Map with case-insensitive lookups, like to pass to other APIs, it’s safer to wrap/copy into a case-insensitive map yourself and then use containsKey/get on that map , rather than keySet().contains.

The one actionable change that might make sense in Spring is a Javadoc clarification for toSingleValueMap(). The current “case-insensitive” wording can be read as “case-insensitive key lookup”, but in practice the returned Map does not guarantee that and its keys reflect whatever casing was stored upstream.

[bclozel]

I agree with @TerryTaoYY

While the current Javadoc underlines the case-sensitivity behavior difference, I don't think this was intentional. asSingleValueMap(), asMultiValueMap(), toSingleValueMap() should be all aligned here and not perform case-insensitive operations. I'm repurposing this issue to a documentation update.