Improve documentation on support for a language-only Locale requested via "Accept-Language"

[chulbert]

@Test
public void resolvePreferredAgainstLanguageOnly() {
    this.resolver.setSupportedLocales(Arrays.asList(GERMANY, US));
    assertThat(this.resolver.resolveLocaleContext(exchange(UK, ENGLISH)).getLocale()).isEqualTo(US);
}

This test should pass. If a client requests en-GB, en and the supported locales are de-DE, en-US then this should resolve to US because en (English of any kind) matches en-US (US English). Instead it incorrectly resolves to en-GB.

Note: There is an existing test with the same name that I believe has this wrong:

@Test
public void resolvePreferredAgainstLanguageOnly() {
    this.resolver.setSupportedLocales(Collections.singletonList(ENGLISH));
    assertThat(this.resolver.resolveLocaleContext(exchange(GERMANY, US, UK)).getLocale()).isEqualTo(ENGLISH);
}

This test should also pass but not because it "matches" -- it should resolve to ENGLISH because that's the only supported locale.

This affects all versions.

[rstoyanchev]

I think this makes sense.

Currently, we have special handling for a language-only, supported Locale, but we don't have that for a language-only, requested Locale. For example if en is requested, it should match to any en-* supported Local, but instead it fails to match, and falls back on the first supported locale. We should be able to return the first matching supported locale (including language and country) since it meets the client (language only) requirement, and is more specific.

This test should also pass but not because it "matches" -- it should resolve to ENGLISH because that's the only supported locale.

We fall back on the default supported Locale, if there is one configured, or otherwise on the first supported Locale. In this case, we just happen to match even earlier on the language. I don't see anything wrong there.

[rstoyanchev]

Team Decision: following an extensive team discussion, first I'll say the current behavior is intentional.

The idea is that a server is in control of what should happen, and can for example be configured to also support en in addition to en-US and en-GB it wants to support requests for a language-only locale such as en, but if it's not added then it means we don't match on such request, and fall back on the default Locale. This is also how java.util.ResourceBundle behaves.

For now I am going to turn this into a documentation issues in order to make it more clear that this is by design.

We can also consider a future enhancement where we take further action if we fall back on the default locale, and there are 1 or more requested locales, and the default locale doesn't match the language of any of them. However, that would be a behavior change and we could only introduce in 6.1 at the earliest.