- Enclosing class:
Locale
There are two types of language ranges: basic and extended. In RFC 4647, the syntax of language ranges is expressed in ABNF as follows:
For example,basic-language-range = (1*8ALPHA *("-" 1*8alphanum)) / "*" extended-language-range = (1*8ALPHA / "*") *("-" (1*8alphanum / "*")) alphanum = ALPHA / DIGIT
"en"
(English), "ja-JP"
(Japanese, Japan),
"*"
(special language range which matches any language tag) are
basic language ranges, whereas "*-CH"
(any languages,
Switzerland), "es-*"
(Spanish, any regions), and
"zh-Hant-*"
(Traditional Chinese, any regions) are extended
language ranges.- Since:
- 1.8
- External Specifications
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final double
A constant holding the maximum value of weight, 1.0, which indicates that the language range is a good fit for the user.static final double
A constant holding the minimum value of weight, 0.0, which indicates that the language range is not a good fit for the user. -
Constructor Summary
ConstructorDescriptionLanguageRange
(String range) Constructs aLanguageRange
using the givenrange
.LanguageRange
(String range, double weight) Constructs aLanguageRange
using the givenrange
andweight
. -
Method Summary
Modifier and TypeMethodDescriptionboolean
Compares this object to the specified object.getRange()
Returns the language range of thisLanguageRange
.double
Returns the weight of thisLanguageRange
.int
hashCode()
Returns a hash code value for this object.static List
<Locale.LanguageRange> mapEquivalents
(List<Locale.LanguageRange> priorityList, Map<String, List<String>> map) Generates a new customized Language Priority List using the givenpriorityList
andmap
.static List
<Locale.LanguageRange> Parses the givenranges
to generate a Language Priority List.static List
<Locale.LanguageRange> Parses the givenranges
to generate a Language Priority List, and then customizes the list using the givenmap
.toString()
Returns an informative string representation of thisLanguageRange
object, consisting of language range and weight if the range is weighted and the weight is less than the max weight.
-
Field Details
-
MAX_WEIGHT
public static final double MAX_WEIGHTA constant holding the maximum value of weight, 1.0, which indicates that the language range is a good fit for the user.- See Also:
-
MIN_WEIGHT
public static final double MIN_WEIGHTA constant holding the minimum value of weight, 0.0, which indicates that the language range is not a good fit for the user.- See Also:
-
-
Constructor Details
-
LanguageRange
Constructs aLanguageRange
using the givenrange
. Note that no validation is done against the IANA Language Subtag Registry at time of construction.This is equivalent to
LanguageRange(range, MAX_WEIGHT)
.- Parameters:
range
- a language range- Throws:
NullPointerException
- if the givenrange
isnull
IllegalArgumentException
- if the givenrange
does not comply with the syntax of the language range mentioned in RFC 4647
-
LanguageRange
Constructs aLanguageRange
using the givenrange
andweight
. Note that no validation is done against the IANA Language Subtag Registry at time of construction.- Parameters:
range
- a language rangeweight
- a weight value betweenMIN_WEIGHT
andMAX_WEIGHT
- Throws:
NullPointerException
- if the givenrange
isnull
IllegalArgumentException
- if the givenrange
does not comply with the syntax of the language range mentioned in RFC 4647 or if the givenweight
is less thanMIN_WEIGHT
or greater thanMAX_WEIGHT
-
-
Method Details
-
getRange
Returns the language range of thisLanguageRange
.- Returns:
- the language range.
-
getWeight
public double getWeight()Returns the weight of thisLanguageRange
.- Returns:
- the weight value.
-
parse
Parses the givenranges
to generate a Language Priority List.This method performs a syntactic check for each language range in the given
ranges
but doesn't do validation using the IANA Language Subtag Registry.The
ranges
to be given can take one of the following forms:"Accept-Language: ja,en;q=0.4" (weighted list with Accept-Language prefix) "ja,en;q=0.4" (weighted list) "ja,en" (prioritized list)
In a weighted list, each language range is given a weight value. The weight value is identical to the "quality value" in RFC 2616, and it expresses how much the user prefers the language. A weight value is specified after a corresponding language range followed by";q="
, and the default weight value isMAX_WEIGHT
when it is omitted.Unlike a weighted list, language ranges in a prioritized list are sorted in the descending order based on its priority. The first language range has the highest priority and meets the user's preference most.
In either case, language ranges are sorted in descending order in the Language Priority List based on priority or weight. If a language range appears in the given
ranges
more than once, only the first one is included on the Language Priority List.The returned list consists of language ranges from the given
ranges
and their equivalents found in the IANA Language Subtag Registry. For example, if the givenranges
is"Accept-Language: iw,en-us;q=0.7,en;q=0.3"
, the elements in the list to be returned are:Range Weight "iw" (older tag for Hebrew) 1.0 "he" (new preferred code for Hebrew) 1.0 "en-us" (English, United States) 0.7 "en" (English) 0.3
Two language ranges,"iw"
and"he"
, have the same highest priority in the list. By adding"he"
to the user's Language Priority List, locale-matching method can find Hebrew as a matching locale (or language tag) even if the application or system offers only"he"
as a supported locale (or language tag).- Parameters:
ranges
- a list of comma-separated language ranges or a list of language ranges in the form of the "Accept-Language" header defined in RFC 2616- Returns:
- a Language Priority List consisting of language ranges
included in the given
ranges
and their equivalent language ranges if available. The list is modifiable. - Throws:
NullPointerException
- ifranges
is nullIllegalArgumentException
- if a language range or a weight found in the givenranges
is ill-formed- External Specifications
-
parse
Parses the givenranges
to generate a Language Priority List, and then customizes the list using the givenmap
. This method is equivalent tomapEquivalents(parse(ranges), map)
.- Parameters:
ranges
- a list of comma-separated language ranges or a list of language ranges in the form of the "Accept-Language" header defined in RFC 2616map
- a map containing information to customize language ranges- Returns:
- a Language Priority List with customization. The list is modifiable.
- Throws:
NullPointerException
- ifranges
is nullIllegalArgumentException
- if a language range or a weight found in the givenranges
is ill-formed- External Specifications
- See Also:
-
mapEquivalents
public static List<Locale.LanguageRange> mapEquivalents(List<Locale.LanguageRange> priorityList, Map<String, List<String>> map) Generates a new customized Language Priority List using the givenpriorityList
andmap
. If the givenmap
is empty, this method returns a copy of the givenpriorityList
.In the map, a key represents a language range whereas a value is a list of equivalents of it.
'*'
cannot be used in the map. Each equivalent language range has the same weight value as its original language range.An example of map: Key Value "zh" (Chinese) "zh", "zh-Hans"(Simplified Chinese) "zh-HK" (Chinese, Hong Kong) "zh-HK" "zh-TW" (Chinese, Taiwan) "zh-TW"
The customization is performed after modification using the IANA Language Subtag Registry.For example, if a user's Language Priority List consists of five language ranges (
"zh"
,"zh-CN"
,"en"
,"zh-TW"
, and"zh-HK"
), the newly generated Language Priority List which is customized using the above map example will consists of"zh"
,"zh-Hans"
,"zh-CN"
,"zh-Hans-CN"
,"en"
,"zh-TW"
, and"zh-HK"
."zh-HK"
and"zh-TW"
aren't converted to"zh-Hans-HK"
nor"zh-Hans-TW"
even if they are included in the Language Priority List. In this example, mapping is used to clearly distinguish Simplified Chinese and Traditional Chinese.If the
"zh"
-to-"zh"
mapping isn't included in the map, a simple replacement will be performed and the customized list won't include"zh"
and"zh-CN"
.- Parameters:
priorityList
- user's Language Priority Listmap
- a map containing information to customize language ranges- Returns:
- a new Language Priority List with customization. The list is modifiable.
- Throws:
NullPointerException
- ifpriorityList
isnull
- See Also:
-
hashCode
-
equals
Compares this object to the specified object. The result is true if and only if the argument is notnull
and is aLanguageRange
object that contains the samerange
andweight
values as this object. -
toString
Returns an informative string representation of thisLanguageRange
object, consisting of language range and weight if the range is weighted and the weight is less than the max weight.
-