Enhance nullability annotations and documentation in LocalizedText (#6149)
This commit is contained in:
1 parent
f0466c1d8e
commit
f5a5e6a6da
1 file changed
+50
-6
@@ -23,28 +23,60 @@ import com.google.gson.annotations.JsonAdapter;
|
||||
import com.google.gson.stream.JsonReader;
|
||||
import com.google.gson.stream.JsonToken;
|
||||
import com.google.gson.stream.JsonWriter;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
import org.jackhuang.hmcl.util.gson.JsonSerializable;
|
||||
import org.jetbrains.annotations.NotNullByDefault;
|
||||
import org.jetbrains.annotations.Nullable;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.*;
|
||||
|
||||
/// Represents text that may either be locale-independent or stored as values keyed by language tags.
|
||||
///
|
||||
/// The JSON representation accepts either a string or an object. A string is treated as the same text for every
|
||||
/// locale, while an object maps language keys, such as `en`, `zh-Hans`, or `default`, to localized text values.
|
||||
///
|
||||
/// @author Glavo
|
||||
@NotNullByDefault
|
||||
@JsonAdapter(LocalizedText.Adapter.class)
|
||||
@JsonSerializable
|
||||
public final class LocalizedText {
|
||||
/// Locale-independent text used when this instance is not backed by localized values.
|
||||
private final @Nullable String value;
|
||||
|
||||
/// Text values keyed by language keys generated by [LocaleUtils#toLanguageKey(Locale)].
|
||||
private final @Nullable Map<String, String> localizedValues;
|
||||
|
||||
public LocalizedText(String value) {
|
||||
/// Creates a locale-independent text value.
|
||||
///
|
||||
/// When `value` is `null`, [#getText(List)] returns `null` for every candidate locale.
|
||||
///
|
||||
/// @param value the text value, or `null` if the text is absent
|
||||
public LocalizedText(@Nullable String value) {
|
||||
this.value = value;
|
||||
this.localizedValues = null;
|
||||
}
|
||||
|
||||
public LocalizedText(@NotNull Map<String, String> localizedValues) {
|
||||
/// Creates a localized text value backed by language-key mappings.
|
||||
///
|
||||
/// The map is stored directly and is not copied. Later changes to `localizedValues` are visible through this
|
||||
/// instance.
|
||||
///
|
||||
/// @param localizedValues text values keyed by language keys generated by [LocaleUtils#toLanguageKey(Locale)]
|
||||
/// @throws NullPointerException if `localizedValues` is `null`
|
||||
public LocalizedText(Map<String, String> localizedValues) {
|
||||
this.value = null;
|
||||
this.localizedValues = Objects.requireNonNull(localizedValues);
|
||||
}
|
||||
|
||||
public String getText(@NotNull List<Locale> candidates) {
|
||||
/// Returns the best matching text for the given candidate locales.
|
||||
///
|
||||
/// If this instance stores localized values, the candidates are checked in iteration order after conversion with
|
||||
/// [LocaleUtils#toLanguageKey(Locale)]. The first matching value is returned, or `null` if no candidate matches.
|
||||
/// If this instance stores locale-independent text, the stored value is returned without checking `candidates`.
|
||||
///
|
||||
/// @param candidates candidate locales ordered from most preferred to least preferred
|
||||
/// @return the matched text, the locale-independent text, or `null` if no text is available
|
||||
public @Nullable String getText(List<Locale> candidates) {
|
||||
if (localizedValues != null) {
|
||||
for (Locale locale : candidates) {
|
||||
String value = localizedValues.get(LocaleUtils.toLanguageKey(locale));
|
||||
@@ -56,10 +88,17 @@ public final class LocalizedText {
|
||||
return value;
|
||||
}
|
||||
|
||||
/// Gson adapter for the compact localized text JSON representation.
|
||||
static final class Adapter extends TypeAdapter<LocalizedText> {
|
||||
|
||||
/// Reads a localized text value from `null`, a JSON string, or a JSON object.
|
||||
///
|
||||
/// @param jsonReader the reader positioned at the next localized text value
|
||||
/// @return the parsed localized text, or `null` if the next JSON token is `null`
|
||||
/// @throws IOException if reading from `jsonReader` fails
|
||||
/// @throws JsonSyntaxException if the next token is neither `null`, a string, nor an object
|
||||
@Override
|
||||
public LocalizedText read(JsonReader jsonReader) throws IOException {
|
||||
public @Nullable LocalizedText read(JsonReader jsonReader) throws IOException {
|
||||
JsonToken nextToken = jsonReader.peek();
|
||||
if (nextToken == JsonToken.NULL) {
|
||||
return null;
|
||||
@@ -83,8 +122,13 @@ public final class LocalizedText {
|
||||
}
|
||||
}
|
||||
|
||||
/// Writes a localized text value as `null`, a JSON string, or a JSON object.
|
||||
///
|
||||
/// @param jsonWriter the writer that receives the JSON representation
|
||||
/// @param localizedText the localized text to write, or `null` to write a JSON `null`
|
||||
/// @throws IOException if writing to `jsonWriter` fails
|
||||
@Override
|
||||
public void write(JsonWriter jsonWriter, LocalizedText localizedText) throws IOException {
|
||||
public void write(JsonWriter jsonWriter, @Nullable LocalizedText localizedText) throws IOException {
|
||||
if (localizedText == null) {
|
||||
jsonWriter.nullValue();
|
||||
} else if (localizedText.localizedValues != null) {
|
||||
|
||||
Reference in new issue
Block a user