Class Strings.Builder

java.lang.Object

com.lokalized.Strings.Builder

Enclosing interface:

Strings

@NotThreadSafe
public static class Strings.Builder
extends Object

Builder used to construct Strings instances.

This class is intended for use by a single thread.

Since:

3.0.0

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
@NonNull Strings.Builder	bidiIsolation(@Nullable BidiIsolation bidiIsolation)	Applies bidirectional isolation behavior for caller-supplied placeholder values.
@NonNull Strings	build()	Constructs a Strings instance.
@NonNull Strings.Builder	languageRangeEquivalents(@Nullable LanguageRangeEquivalents languageRangeEquivalents)	Applies the source of IANA language-range equivalences, such as the he/iw pair, for this instance.
@NonNull Strings.Builder	localeMatchSupplier(@Nullable Function<@NonNull LocaleMatcher, @NonNull LocaleMatchResult> localeMatchSupplier)	Applies a locale-negotiation-result supplier to this builder.
@NonNull Strings.Builder	localeSupplier(@Nullable Function<@NonNull LocaleMatcher, @NonNull Locale> localeSupplier)	Applies a locale supplier to this builder.
@NonNull Strings.Builder	localizedStringSupplier(@Nullable Supplier<@NonNull Map<@NonNull Locale, ? extends @NonNull Iterable<@NonNull LocalizedString>>> localizedStringSupplier)	Applies a localized string supplier to this builder.
@NonNull Strings.Builder	phoneticResolver(@Nullable PhoneticResolver phoneticResolver)	Applies a phonetic resolver to this builder.
@NonNull Strings.Builder	runtimeLimits(@Nullable TranslationRuntimeLimits runtimeLimits)	Applies safety limits to localized strings construction and translation evaluation.
@NonNull Strings.Builder	tiebreakerLocalesByLanguageCode(@Nullable Map<@NonNull String, @NonNull List<@NonNull Locale>> tiebreakerLocalesByLanguageCode)	Applies a mapping of a well-formed IETF BCP 47 primary language subtag to its ordered "tiebreaker" fallback locales to this builder.
@NonNull Strings.Builder	translationFailureHandler(@Nullable TranslationFailureHandler translationFailureHandler)	Applies a translation failure handler to this builder.
@NonNull Strings.Builder	translationFallbackObserver(@Nullable TranslationFallbackObserver translationFallbackObserver)	Applies an observer for translations supplied by a later locale candidate after earlier candidates failed.
@NonNull Strings.Builder	translationFallbackPolicy(@Nullable TranslationFallbackPolicy translationFallbackPolicy)	Applies the policy that decides whether failed locale attempts continue to fallback candidates.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

localizedStringSupplier

public @NonNull Strings.Builder localizedStringSupplier(@Nullable Supplier<@NonNull Map<@NonNull Locale, ? extends @NonNull Iterable<@NonNull LocalizedString>>> localizedStringSupplier)

Applies a localized string supplier to this builder.

Locale keys returned by the supplier must be well-formed and must render to distinct IETF BCP 47 language tags. The returned map, its keys, each per-locale iterable, and every localized string must be non-null. Each per-locale iterable must contain unique translation keys.

Parameters:

localizedStringSupplier - localized string supplier, may be null

Returns:

this builder instance, useful for chaining. not null

localeSupplier

public @NonNull Strings.Builder localeSupplier(@Nullable Function<@NonNull LocaleMatcher, @NonNull Locale> localeSupplier)

Applies a locale supplier to this builder.

The supplier may be invoked concurrently after the Strings instance is built and must be thread-safe. It must return a well-formed IETF BCP 47 locale.

Parameters:

localeSupplier - locale supplier, may be null

Returns:

this builder instance, useful for chaining. not null

localeMatchSupplier

public @NonNull Strings.Builder localeMatchSupplier(@Nullable Function<@NonNull LocaleMatcher, @NonNull LocaleMatchResult> localeMatchSupplier)

Applies a locale-negotiation-result supplier to this builder.

Prefer this over localeSupplier(Function) when callers of Strings.getResult(String) should receive the original negotiation diagnostics. The supplier may be invoked concurrently and must be thread-safe. Supplying a non-null value replaces any locale supplier.

Parameters:

localeMatchSupplier - locale-match supplier, may be null

Returns:

this builder, not null

Since:

3.0.0

tiebreakerLocalesByLanguageCode

public @NonNull Strings.Builder tiebreakerLocalesByLanguageCode(@Nullable Map<@NonNull String, @NonNull List<@NonNull Locale>> tiebreakerLocalesByLanguageCode)

Applies a mapping of a well-formed IETF BCP 47 primary language subtag to its ordered "tiebreaker" fallback locales to this builder.

Deprecated language aliases are canonicalized, so aliases such as he and iw must not both be supplied. Each list must be a duplicate-free exact permutation of the loaded Locales whose normalized primary language matches its key. This configuration is validated by build().

Parameters:

tiebreakerLocalesByLanguageCode - "tiebreaker" fallback locales, may be null; keys, lists, and locales must not be null

Returns:

this builder instance, useful for chaining. not null

phoneticResolver

public @NonNull Strings.Builder phoneticResolver(@Nullable PhoneticResolver phoneticResolver)

Applies a phonetic resolver to this builder.

The resolver may be invoked concurrently after the Strings instance is built and must be thread-safe.

Parameters:

phoneticResolver - phonetic resolver, may be null (defaults to fail-fast resolver)

Returns:

this builder instance, useful for chaining. not null

translationFailureHandler

public @NonNull Strings.Builder translationFailureHandler(@Nullable TranslationFailureHandler translationFailureHandler)

Applies a translation failure handler to this builder.

The handler may be invoked concurrently after the Strings instance is built and must be thread-safe.

Parameters:

translationFailureHandler - handler for failed lookups, may be null (defaults to returning the key)

Returns:

this builder instance, useful for chaining. not null

translationFallbackPolicy

public @NonNull Strings.Builder translationFallbackPolicy(@Nullable TranslationFallbackPolicy translationFallbackPolicy)

Applies the policy that decides whether failed locale attempts continue to fallback candidates.

The policy may be invoked concurrently after the Strings instance is built and must be thread-safe. The default TranslationFallbackPolicy.fallbackOnMissingTranslationOrNoMatchingAlternative() policy stops on TranslationFailureReason.RESOLUTION_FAILURE, including failures while evaluating an expression-fragment predicate or interpolating its selected/default fragment.

Parameters:

translationFallbackPolicy - locale fallback policy, may be null to use the safe default

Returns:

this builder, not null

translationFallbackObserver

public @NonNull Strings.Builder translationFallbackObserver(@Nullable TranslationFallbackObserver translationFallbackObserver)

Applies an observer for translations supplied by a later locale candidate after earlier candidates failed.

The observer runs once before a successful lookup returns. It may be invoked concurrently and must be thread-safe. Observer exceptions propagate directly to the caller.

Parameters:

translationFallbackObserver - successful fallback observer, may be null to disable observation

Returns:

this builder, not null

Since:

3.1.1

runtimeLimits

public @NonNull Strings.Builder runtimeLimits(@Nullable TranslationRuntimeLimits runtimeLimits)

Applies safety limits to localized strings construction and translation evaluation.

Expression limits apply to both whole-message alternatives and expression-fragment alternatives. Generated-placeholder depth and expansion limits are shared by language-form and expression-selected fragments. The interpolated-output limit also bounds caller-supplied CharSequence values materialized for phonetic resolution.

Parameters:

runtimeLimits - runtime limits, may be null to use the library defaults

Returns:

this builder, not null

Since:

3.0.0

bidiIsolation

public @NonNull Strings.Builder bidiIsolation(@Nullable BidiIsolation bidiIsolation)

Applies bidirectional isolation behavior for caller-supplied placeholder values.

Translation-owned text in generated fragments is not isolated; caller-supplied values interpolated into those fragments use this policy.

Parameters:

bidiIsolation - bidi isolation behavior, may be null (defaults to isolating caller-supplied values in RTL locales)

Returns:

this builder instance, useful for chaining. not null

languageRangeEquivalents

public @NonNull Strings.Builder languageRangeEquivalents(@Nullable LanguageRangeEquivalents languageRangeEquivalents)

Applies the source of IANA language-range equivalences, such as the he/iw pair, for this instance.

The source governs LocaleMatcher.parseLanguageRanges(String), LocaleMatcher.bestMatchForAcceptLanguage(String), and the equivalences locale matching recognizes for each requested range, so it can change which loaded locale a request selects. LanguageRangeEquivalents.IANA_REGISTRY uses the IANA Language Subtag Registry snapshot bundled in Lokalized and supplies the same equivalents on every JDK; LanguageRangeEquivalents.JDK uses the running JDK's table, as Lokalized 3.0.0 did. A range list parsed by the caller with Locale.LanguageRange.parse(String) carries the JDK's equivalents whatever this is set to; parse it with LocaleMatcher.parseLanguageRanges(String) to apply this setting.

Parameters:

languageRangeEquivalents - equivalence source, may be null (defaults to LanguageRangeEquivalents.IANA_REGISTRY)

Returns:

this builder instance, useful for chaining. not null

Since:

3.1.0

build

public @NonNull Strings build()

Constructs a Strings instance.

Returns:

a Strings instance, not null

Throws:

IllegalArgumentException - if required localized-string or locale suppliers are missing, a configured locale is malformed, localized-string locale keys render to duplicate language tags, tiebreaker keys are invalid or collide after canonicalization, a tiebreaker list is not an exact permutation of its language's loaded locales, or supplied localized strings are invalid, including an alternative graph nested more than 128 levels deep

ExpressionEvaluationException - if an expression cannot be compiled, including when it exceeds the configured runtime limits