Locale.LanguageRange

public static final class Locale.LanguageRange extends Object

This class expresses a Language Range defined in RFC 4647 Matching of Language Tags. A language range is an identifier which is used to select language tag(s) meeting specific requirements by using the mechanisms described in Locale Matching. A list which represents a user's preferences and consists of language ranges is called a Language Priority List.

There are two types of language ranges: basic and extended. In RFC 4647, the syntax of language ranges is expressed in ABNF as follows:

     basic-language-range    = (1*8ALPHA *("-" 1*8alphanum)) / "*"
     extended-language-range = (1*8ALPHA / "*")
                               *("-" (1*8alphanum / "*"))
     alphanum                = ALPHA / DIGIT

For example, "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.

Constant Summary

double	MAX_WEIGHT	A constant holding the maximum value of weight, 1.0, which indicates that the language range is a good fit for the user.
double	MIN_WEIGHT	A constant holding the minimum value of weight, 0.0, which indicates that the language range is not a good fit for the user.

Public Constructor Summary

	LanguageRange(String range) Constructs a `LanguageRange` using the given `range`.
	LanguageRange(String range, double weight) Constructs a `LanguageRange` using the given `range` and `weight`.

Public Method Summary

boolean	equals(Object obj) Compares this object to the specified object.
String	getRange() Returns the language range of this `LanguageRange`.
double	getWeight() Returns the weight of this `LanguageRange`.
int	hashCode() Returns a hash code value for the object.
static List<Locale.LanguageRange>	mapEquivalents(List<Locale.LanguageRange> priorityList, Map<String, List<String>> map) Generates a new customized Language Priority List using the given `priorityList` and `map`.
static List<Locale.LanguageRange>	parse(String ranges) Parses the given `ranges` to generate a Language Priority List.
static List<Locale.LanguageRange>	parse(String ranges, Map<String, List<String>> map) Parses the given `ranges` to generate a Language Priority List, and then customizes the list using the given `map`.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.

Constants

public static final double MAX_WEIGHT

A constant holding the maximum value of weight, 1.0, which indicates that the language range is a good fit for the user.

Constant Value: 1.0

public static final double MIN_WEIGHT

A constant holding the minimum value of weight, 0.0, which indicates that the language range is not a good fit for the user.

Constant Value: 0.0

Public Constructors

public LanguageRange (String range)

Constructs a LanguageRange using the given range. 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 given `range` is `null`

public LanguageRange (String range, double weight)

Constructs a LanguageRange using the given range and weight. Note that no validation is done against the IANA Language Subtag Registry at time of construction.

Parameters

range	a language range
weight	a weight value between `MIN_WEIGHT` and `MAX_WEIGHT`

Throws

NullPointerException	if the given `range` is `null`
IllegalArgumentException	if the given `weight` is less than `MIN_WEIGHT` or greater than `MAX_WEIGHT`

Public Methods

public boolean equals (Object obj)

Compares this object to the specified object. The result is true if and only if the argument is not null and is a LanguageRange object that contains the same range and weight values as this object.

Parameters

obj	the object to compare with

Returns

true if this object's range and weight are the same as the obj's; false otherwise.

public String getRange ()

Returns the language range of this LanguageRange.

Returns

the language range.

public double getWeight ()

Returns the weight of this LanguageRange.

Returns

the weight value.

public int hashCode ()

Returns a hash code value for the object.

Returns

a hash code value for this object.

public static List<Locale.LanguageRange> mapEquivalents (List<Locale.LanguageRange> priorityList, Map<String, List<String>> map)

Generates a new customized Language Priority List using the given priorityList and map. If the given map is empty, this method returns a copy of the given priorityList.

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 List
map	a map containing information to customize language ranges

Returns

a new Language Priority List with customization. The list is modifiable.

Throws

NullPointerException	if `priorityList` is `null`

public static List<Locale.LanguageRange> parse (String ranges)

Parses the given ranges 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 is MAX_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 given ranges 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	if `ranges` is null
IllegalArgumentException	if a language range or a weight found in the given `ranges` is ill-formed

public static List<Locale.LanguageRange> parse (String ranges, Map<String, List<String>> map)

Parses the given ranges to generate a Language Priority List, and then customizes the list using the given map. This method is equivalent to mapEquivalents(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 2616
map	a map containing information to customize language ranges

Returns

a Language Priority List with customization. The list is modifiable.

Throws

NullPointerException	if `ranges` is null
IllegalArgumentException	if a language range or a weight found in the given `ranges` is ill-formed

Locale.LanguageRange

See Also

Constant Summary

Public Constructor Summary

Public Method Summary

Inherited Method Summary

Constants

public static final double MAX_WEIGHT

public static final double MIN_WEIGHT

Public Constructors

public LanguageRange (String range)

Parameters

Throws

public LanguageRange (String range, double weight)

Parameters

Throws

Public Methods

public boolean equals (Object obj)

Parameters

Returns

public String getRange ()

Returns

public double getWeight ()

Returns

public int hashCode ()

Returns

public static List<Locale.LanguageRange> mapEquivalents (List<Locale.LanguageRange> priorityList, Map<String, List<String>> map)

Parameters

Returns

Throws

See Also

public static List<Locale.LanguageRange> parse (String ranges)

Parameters

Returns

Throws

public static List<Locale.LanguageRange> parse (String ranges, Map<String, List<String>> map)

Parameters

Returns

Throws

See Also