com.ibm.icu.util.LocalePriorityList Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of icu4j Show documentation
Show all versions of icu4j Show documentation
International Component for Unicode for Java (ICU4J) is a mature, widely used Java library
providing Unicode and Globalization support
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html#License
/*
*******************************************************************************
* Copyright (C) 2010-2016, Google, Inc.; International Business Machines *
* Corporation and others. All Rights Reserved. *
*******************************************************************************
*/
package com.ibm.icu.util;
import java.util.Collections;
import java.util.Comparator;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Set;
import java.util.TreeMap;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* Provides an immutable list of languages/locales in priority order.
* The string format is based on the Accept-Language format
* (RFC 2616 Section 14.4), such as
* "af, en, fr;q=0.9". Syntactically it is slightly
* more lenient, in allowing extra whitespace between elements, extra commas,
* and more than 3 decimals (on input). The qvalues must be between 0 and 1.
*
* In theory, Accept-Language indicates the relative 'quality' of each item,
* but in practice, all of the browsers just take an ordered list, like
* "en, fr, de", and synthesize arbitrary quality values that put these in the
* right order, like: "en, fr;q=0.7, de;q=0.3". The quality values in these de facto
* semantics thus have nothing to do with the relative qualities of the
* original. Accept-Language also doesn't
* specify the interpretation of multiple instances, eg what "en, fr, en;q=.5"
* means.
*
There are various ways to build a LocalePriorityList, such
* as using the following equivalent patterns:
*
*
* list = LocalePriorityList.add("af, en, fr;q=0.9").build();
*
* list2 = LocalePriorityList
* .add(ULocale.forString("af"))
* .add(ULocale.ENGLISH)
* .add(ULocale.FRENCH, 0.9d)
* .build();
*
* When the list is built, the internal values are sorted in descending order by weight,
* and then by input order.
* That is, if two languages/locales have the same weight, the first one in the original order comes first.
* If exactly the same language tag appears multiple times, the last one wins.
*
* There are two options when building.
* If preserveWeights are on, then "de;q=0.3, ja;q=0.3, en, fr;q=0.7, de " would result in the following:
*
en;q=1.0
* de;q=1.0
* fr;q=0.7
* ja;q=0.3
* If it is off (the default), then all weights are reset to 1.0 after reordering.
* This is to match the effect of the Accept-Language semantics as used in browsers, and results in the following:
* * en;q=1.0
* de;q=1.0
* fr;q=1.0
* ja;q=1.0
* @author [email protected]
* @stable ICU 4.4
*/
public class LocalePriorityList implements Iterable {
private static final Double D1 = 1.0d;
private static final Pattern languageSplitter = Pattern.compile("\\s*,\\s*");
private static final Pattern weightSplitter = Pattern
.compile("\\s*(\\S*)\\s*;\\s*q\\s*=\\s*(\\S*)");
private final Map languagesAndWeights;
/**
* Creates a Builder and adds locales, each with weight 1.0.
*
* @param locales locales/languages to be added
* @return a new builder with these locales, for chaining
* @stable ICU 4.4
*/
public static Builder add(ULocale... locales) {
return new Builder().add(locales);
}
/**
* Creates a Builder and adds a locale with a specified weight.
* A zero or negative weight leads to removing the locale.
* A weight greater than 1 is pinned to 1.
*
* @param locale locale/language to be added
* @param weight value from 0.0 to 1.0
* @return a new builder with this locale, for chaining
* @stable ICU 4.4
*/
public static Builder add(ULocale locale, final double weight) {
return new Builder().add(locale, weight);
}
/**
* Creates a Builder and adds locales with weights.
*
* @param list list of locales with weights
* @return a new builder with these locales, for chaining
* @stable ICU 4.4
*/
public static Builder add(LocalePriorityList list) {
return new Builder(list);
}
/**
* Creates a Builder, parses the RFC 2616 string, and adds locales with weights accordingly.
*
* @param acceptLanguageString String in RFC 2616 format (leniently parsed)
* @return a new builder with these locales, for chaining
* @stable ICU 4.4
*/
public static Builder add(String acceptLanguageString) {
return new Builder().add(acceptLanguageString);
}
/**
* Returns the weight for a given language/locale, or null if there is none.
* Note that the weights may be adjusted from those used to build the list.
*
* @param locale to get weight of
* @return weight
* @stable ICU 4.4
*/
public Double getWeight(ULocale locale) {
return languagesAndWeights.get(locale);
}
/**
* Returns the locales as an immutable Set view.
* The set has the same iteration order as this object itself.
*
* @return the locales
* @draft ICU 65
* @provisional This API might change or be removed in a future release.
*/
public Set getULocales() {
return languagesAndWeights.keySet();
}
/**
* {@inheritDoc}
* @stable ICU 4.4
*/
@Override
public String toString() {
final StringBuilder result = new StringBuilder();
for (Entry entry : languagesAndWeights.entrySet()) {
ULocale language = entry.getKey();
double weight = entry.getValue();
if (result.length() != 0) {
result.append(", ");
}
result.append(language);
if (weight != 1.0) {
result.append(";q=").append(weight);
}
}
return result.toString();
}
/**
* {@inheritDoc}
* @stable ICU 4.4
*/
@Override
public Iterator iterator() {
return languagesAndWeights.keySet().iterator();
}
/**
* {@inheritDoc}
* @stable ICU 4.4
*/
@Override
public boolean equals(final Object o) {
if (o == null) {
return false;
}
if (this == o) {
return true;
}
try {
final LocalePriorityList that = (LocalePriorityList) o;
return languagesAndWeights.equals(that.languagesAndWeights);
} catch (final RuntimeException e) {
return false;
}
}
/**
* {@inheritDoc}
* @stable ICU 4.4
*/
@Override
public int hashCode() {
return languagesAndWeights.hashCode();
}
// ==================== Privates ====================
private LocalePriorityList(final Map languageToWeight) {
this.languagesAndWeights = languageToWeight;
}
/**
* Class used for building LocalePriorityLists.
* @stable ICU 4.4
*/
public static class Builder {
/**
* These store the input languages and weights, in chronological order,
* where later additions override previous ones.
*/
private Map languageToWeight;
/**
* The builder is reusable but rarely reused. Avoid cloning the map when not needed.
* Exactly one of languageToWeight and built is null.
*/
private LocalePriorityList built;
private boolean hasWeights = false; // other than 1.0
/**
* Private constructor, only used by LocalePriorityList
*/
private Builder() {
languageToWeight = new LinkedHashMap<>();
}
private Builder(LocalePriorityList list) {
built = list;
for (Double value : list.languagesAndWeights.values()) {
double weight = value;
assert 0.0 < weight && weight <= 1.0;
if (weight != 1.0) {
hasWeights = true;
break;
}
}
}
/**
* Creates a LocalePriorityList. This is equivalent to
* {@link Builder#build(boolean) Builder.build(false)}.
*
* @return A LocalePriorityList
* @stable ICU 4.4
*/
public LocalePriorityList build() {
return build(false);
}
/**
* Creates a LocalePriorityList.
*
* @param preserveWeights when true, each locale's given weight is preserved.
* @return A LocalePriorityList
* @stable ICU 4.4
*/
public LocalePriorityList build(boolean preserveWeights) {
if (built != null) {
// Calling build() again without changing anything in between.
// Just return the same immutable list.
return built;
}
Map temp;
if (hasWeights) {
// Walk through the input list, collecting the items with the same weights.
final TreeMap> weightToLanguages =
new TreeMap<>(myDescendingDouble);
for (Entry entry : languageToWeight.entrySet()) {
ULocale lang = entry.getKey();
Double weight = entry.getValue();
List s = weightToLanguages.get(weight);
if (s == null) {
weightToLanguages.put(weight, s = new LinkedList<>());
}
s.add(lang);
}
// We now have a bunch of items sorted by weight, then chronologically.
// We can now create a list in the right order.
if (weightToLanguages.size() <= 1) {
// There is at most one weight.
temp = languageToWeight;
if (weightToLanguages.isEmpty() || weightToLanguages.firstKey() == 1.0) {
hasWeights = false;
}
} else {
temp = new LinkedHashMap<>();
for (Entry> langEntry : weightToLanguages.entrySet()) {
final Double weight = preserveWeights ? langEntry.getKey() : D1;
for (final ULocale lang : langEntry.getValue()) {
temp.put(lang, weight);
}
}
}
} else {
// Nothing to sort.
temp = languageToWeight;
}
languageToWeight = null;
return built = new LocalePriorityList(Collections.unmodifiableMap(temp));
}
/**
* Adds locales with weights.
*
* @param list list of locales with weights
* @return this, for chaining
* @stable ICU 4.4
*/
public Builder add(final LocalePriorityList list) {
for (Entry entry : list.languagesAndWeights.entrySet()) {
add(entry.getKey(), entry.getValue());
}
return this;
}
/**
* Adds a locale with weight 1.0.
*
* @param locale to add with weight 1.0
* @return this, for chaining
* @stable ICU 4.4
*/
public Builder add(final ULocale locale) {
return add(locale, 1.0);
}
/**
* Adds locales, each with weight 1.0.
*
* @param locales locales/languages to be added
* @return this, for chaining.
* @stable ICU 4.4
*/
public Builder add(ULocale... locales) {
for (final ULocale languageCode : locales) {
add(languageCode, 1.0);
}
return this;
}
/**
* Adds a locale with a specified weight.
* Overrides any previous weight for the locale.
* A zero or negative weight leads to removing the locale.
* A weight greater than 1 is pinned to 1.
*
* @param locale language/locale to add
* @param weight value between 0.0 and 1.1
* @return this, for chaining.
* @stable ICU 4.4
*/
public Builder add(final ULocale locale, double weight) {
if (languageToWeight == null) {
// Builder reuse after build().
languageToWeight = new LinkedHashMap<>(built.languagesAndWeights);
built = null;
}
if (languageToWeight.containsKey(locale)) {
languageToWeight.remove(locale);
}
Double value;
if (weight <= 0.0) {
return this; // skip zeros
} else if (weight >= 1.0) {
value = D1;
} else {
value = weight;
hasWeights = true;
}
languageToWeight.put(locale, value);
return this;
}
/**
* Parses the RFC 2616 string, and adds locales with weights accordingly.
*
* @param acceptLanguageList in RFC 2616 format (leniently parsed)
* @return this, for chaining.
* @stable ICU 4.4
*/
public Builder add(final String acceptLanguageList) {
final String[] items = languageSplitter.split(acceptLanguageList.trim());
final Matcher itemMatcher = weightSplitter.matcher("");
for (final String item : items) {
if (itemMatcher.reset(item).matches()) {
final ULocale language = new ULocale(itemMatcher.group(1));
final double weight = Double.parseDouble(itemMatcher.group(2));
if (!(0.0 <= weight && weight <= 1.0)) { // do ! for NaN
throw new IllegalArgumentException(
"Illegal weight, must be 0..1: " + weight);
}
add(language, weight);
} else if (item.length() != 0) {
add(new ULocale(item));
}
}
return this;
}
}
private static Comparator myDescendingDouble = new Comparator() {
@Override
public int compare(Double o1, Double o2) {
int result = o1.compareTo(o2);
return result > 0 ? -1 : result < 0 ? 1 : 0; // Reverse the order.
}
};
}