Enhance nullability annotations and documentation in LocalizedText (#6149)

This commit is contained in:
Glavo authored and GitHub committed 2026-05-28 20:19:16 +08:00
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) {