Summary

• The implementation of Locale.filterTags()/lookupTag() methods should not return lowercased matching language tags, the APIs should preserve the case of matching language tag(s).
• The implementation of Locale.filter()/Locale.filterTags() methods should not return duplicate matching tags, the APIs should ensure that only unique matching tags are returned.

Problem

• The current implementation of Locale.filterTags()/lookupTag() methods convert the input tags to lowercase and return the lowercased matching tags.
• The current implementation of Locale.filter()/Locale.filterTags() methods return duplicate matching tags

Solution

The language tags/subtags are case insensitive and comparison should be done in the case insensitive manner. However, instead of returning the lowercased matching tags, the Locale.filterTags()/lookupTag() methods should preserve the case of matching language tags. Also, the Locale.filter()/Locale.filterTags() methods should not return duplicate matching tags. An explanation should be added to define the related behavior of these APIs.

Specification

1) Changing the specification of filter(List<LanguageRange>, Collection<Locale>, FilteringMode)

from:

* Returns a list of matching {@code Locale} instances using the filtering
* mechanism defined in RFC 4647.

to:

 * Returns a list of matching {@code Locale} instances using the filtering
 * mechanism defined in RFC 4647.
 *
 * This filter operation on the given {@code locales} ensures that only
 * unique matching locale(s) are returned.

2) Changing the specification of filter(List<LanguageRange>, Collection<Locale>)

from:

* {@link #filter(List, Collection, FilteringMode)} when {@code mode} is
* {@link FilteringMode#AUTOSELECT_FILTERING}.

to:

 * {@link #filter(List, Collection, FilteringMode)} when {@code mode} is
 * {@link FilteringMode#AUTOSELECT_FILTERING}.
 *
 * This filter operation on the given {@code locales} ensures that only
 * unique matching locale(s) are returned.

3) Changing the specification of filterTags(List<LanguageRange>, Collection<String>, FilteringMode)

from:

* Returns a list of matching languages tags using the basic filtering
* mechanism defined in RFC 4647.

to:

 * Returns a list of matching languages tags using the basic filtering
 * mechanism defined in RFC 4647.
 *
 * This filter operation on the given {@code tags} ensures that only
 * unique matching tag(s) are returned with preserved case. In case of
 * duplicate matching tags with the case difference, the first matching
 * tag with preserved case is returned.
 * For Example, "de-ch" is returned out of the duplicate matching tags
 * "de-ch" and "de-CH", if "de-ch" is checked first for matching in the
 * given {@code tags}. Note that if the given {@code tags} is an unordered
 * {@code Collection}, the returned matching tag out of duplicate tags is
 * subject to change, depending on the implementation of the
 * {@code Collection}.

4) Changing the specification of filterTags(List<LanguageRange>, Collection<String>)

from:

* {@link #filterTags(List, Collection, FilteringMode)} when {@code mode}
* is {@link FilteringMode#AUTOSELECT_FILTERING}.

to:

 * {@link #filterTags(List, Collection, FilteringMode)} when {@code mode}
 * is {@link FilteringMode#AUTOSELECT_FILTERING}.
 *
 * This filter operation on the given {@code tags} ensures that only
 * unique matching tag(s) are returned with preserved case. In case of
 * duplicate matching tags with the case difference, the first matching
 * tag with preserved case is returned.
 * For Example, "de-ch" is returned out of the duplicate matching tags
 * "de-ch" and "de-CH", if "de-ch" is checked first for matching in the
 * given {@code tags}. Note that if the given {@code tags} is an unordered
 * {@code Collection}, the returned matching tag out of duplicate tags is
 * subject to change, depending on the implementation of the
 * {@code Collection}.

5) Changing the specification of lookupTag(List<LanguageRange>, Collection<String>)

from:

* Returns the best-matching language tag using the lookup mechanism
* defined in RFC 4647.

to:

 * Returns the best-matching language tag using the lookup mechanism
 * defined in RFC 4647.
 * 
 * This lookup operation on the given {@code tags} ensures that the
 * first matching tag with preserved case is returned.