io.github.freya022.botcommands.api.localization.providers.LocalizationMapProvider Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of BotCommands Show documentation

A Kotlin-first (and Java) framework that makes creating Discord bots a piece of cake, using the JDA library.

There is a newer version: 3.0.0-alpha.18

package io.github.freya022.botcommands.api.localization.providers;

import io.github.freya022.botcommands.api.core.service.annotations.BService;
import io.github.freya022.botcommands.api.core.service.annotations.InterfacedService;
import io.github.freya022.botcommands.api.localization.LocalizationMap;
import io.github.freya022.botcommands.api.localization.readers.LocalizationMapReader;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.Locale;
import java.util.ResourceBundle;

/**
 * Supplies a {@link LocalizationMap} for the requested bundle name and locale.
 * 
This is an intermediary step, often using existing {@link LocalizationMapReader}s.
 *
 * 
 * Usage: Register your instance as a service with {@link BService}.
 *
 * @see DefaultLocalizationMapProvider
 * @see InterfacedService @InterfacedService
 */
@InterfacedService(acceptMultiple = true)
public interface LocalizationMapProvider {
    ResourceBundle.Control CONTROL = ResourceBundle.Control.getNoFallbackControl(ResourceBundle.Control.FORMAT_DEFAULT);

    /**
     * Loads a localization map with the requested name and requested locale.
     * 
This may return a localization bundle with a broader locale,
     * which will be returned by {@link LocalizationMap#getEffectiveLocale()}.
     * 
This may include parent bundles.
     *
     * @param baseName        The base name of the localization bundle
     * @param requestedLocale The requested locale
     *
     * @return A {@link LocalizationMap} instance with the requested data,
     * or {@code null} if no bundle could be read, or a (logged) exception happened.
     */
    @Nullable
    LocalizationMap fromBundleOrParent(@NotNull String baseName, @NotNull Locale requestedLocale);

    /**
     * Loads a localization map with the requested name and requested locale.
     * 
This may return a localization bundle with a broader locale,
     * which must be returned by {@link LocalizationMap#getEffectiveLocale()}.
     *
     * Note: this does NOT include parent bundles.
     *
     * @param baseName        The base name of the localization bundle
     * @param requestedLocale The requested locale
     *
     * @return A {@link LocalizationMap} instance with the requested data,
     * or {@code null} if no bundle could be read, or a (logged) exception happened.
     */
    @Nullable
    LocalizationMap fromBundle(@NotNull String baseName, @NotNull Locale requestedLocale);
}