001/*
002 * PlotSquared, a land and world management plugin for Minecraft.
003 * Copyright (C) IntellectualSites <https://intellectualsites.com>
004 * Copyright (C) IntellectualSites team and contributors
005 *
006 * This program is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU General Public License for more details.
015 *
016 * You should have received a copy of the GNU General Public License
017 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
018 */
019package com.plotsquared.core.configuration.caption;
020
021import org.checkerframework.checker.nullness.qual.NonNull;
022
023import java.util.Locale;
024import java.util.Set;
025
026/**
027 * Map containing mappings between {@link TranslatableCaption captions} and
028 * {@link net.kyori.adventure.text.Component components}
029 */
030public interface CaptionMap {
031
032    /**
033     * Get a message using the server locale
034     *
035     * @param caption Caption containing the caption key
036     * @return Component
037     * @throws NoSuchCaptionException if no caption with the given key exists
038     */
039    @NonNull String getMessage(final @NonNull TranslatableCaption caption) throws NoSuchCaptionException;
040
041    /**
042     * Get a message using a specific locale
043     *
044     * @param caption      Caption containing the caption key
045     * @param localeHolder Holder that determines the message locale
046     * @return Component
047     * @throws NoSuchCaptionException if no caption with the given key exists
048     */
049    @NonNull String getMessage(final @NonNull TranslatableCaption caption, final @NonNull LocaleHolder localeHolder) throws
050            NoSuchCaptionException;
051
052    /**
053     * Check if the map supports a given locale
054     *
055     * @param locale Locale
056     * @return {@code true} if the map supports the locale
057     */
058    boolean supportsLocale(final @NonNull Locale locale);
059
060    /**
061     * Get the locale of the messages stored in the map
062     *
063     * @return Message locale
064     */
065    @NonNull Locale getLocale();
066
067    /**
068     * Gets a copy of the set of captions stored in the CaptionMap
069     *
070     * @return An immutable set of TranslatableCaption
071     */
072    @NonNull Set<TranslatableCaption> getCaptions();
073
074    class NoSuchCaptionException extends IllegalArgumentException {
075
076        public NoSuchCaptionException(final @NonNull NamespacedCaption caption) {
077            super(String.format("No caption with the key '%s:%s' exists in the map", caption.getNamespace(), caption.getKey()));
078        }
079
080    }
081
082}