result = new CompletableFuture<>();
+
+ this.client.sendAsync(request, HttpResponse.BodyHandlers.ofString()).thenApply(stringHttpResponse -> {
+ final int statusCode = stringHttpResponse.statusCode();
+ if (statusCode == 404) {
+ result.complete(null);
+ } else if (statusCode != 200) {
+ result.completeExceptionally(new IOException("The server could not handle the request."));
+ } else {
+ result.complete(stringHttpResponse.body());
+ }
+ return null;
+ });
+
+ return result;
+ }
+
+ @Contract(pure = true)
+ public @NotNull String generateLink(String token) {
+ return root.toString() + "?token=" + token;
+ }
+
+ /**
+ * @param input initial miniMessage
+ * @param command command with {token}
+ * @param app app name
+ * @return the link
+ */
+ @Contract(pure = true)
+ public @NotNull String startSessionAndGenerateLink(String input, String command, String app) {
+ try {
+ return generateLink(startSession(input, command, app).get(10, TimeUnit.SECONDS));
+ } catch (InterruptedException | ExecutionException | TimeoutException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ /**
+ * @param command command with {token}
+ * @return the link
+ */
+ @Contract(pure = true)
+ public @NotNull String startSessionAndGenerateLink(String command) {
+ try {
+ return generateLink(startSession("", command, API.get().getVersion()).get(10, TimeUnit.SECONDS));
+ } catch (InterruptedException | ExecutionException | TimeoutException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ /**
+ * @param command command with {token}
+ * @param app app
+ * @return the link
+ */
+ @Contract(pure = true)
+ public @NotNull String startSessionAndGenerateLink(String command, String app) {
+ try {
+ return generateLink(startSession("", command, app).get(10, TimeUnit.SECONDS));
+ } catch (InterruptedException | ExecutionException | TimeoutException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ /**
+ * @param message the initial message
+ * @param command command with {token}
+ * @param app app
+ * @return the link
+ */
+ @Contract(pure = true)
+ public @NotNull String startSessionAndGenerateLink(@NotNull Message message, String command, String app) {
+ try {
+ return generateLink(startSession(message.getMiniMessage(), command, app).get(10, TimeUnit.SECONDS));
+ } catch (InterruptedException | ExecutionException | TimeoutException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ private @NotNull String constructBody(final @NotNull String input, final @NotNull String command, final @NotNull String application) {
+ return String.format("{\"input\":\"%s\",\"command\":\"%s\",\"application\":\"%s\"}", input, command, application);
+ }
+
+ @Contract(pure = true)
+ public @NotNull String getClientInformation() {
+ return client + "@" + root;
+ }
+}
\ No newline at end of file
diff --git a/API/src/main/java/net/juligames/core/api/external/tokenfix.diff b/API/src/main/java/net/juligames/core/api/external/tokenfix.diff
new file mode 100644
index 00000000..f10ad452
--- /dev/null
+++ b/API/src/main/java/net/juligames/core/api/external/tokenfix.diff
@@ -0,0 +1,12 @@
+41c41
+< private static final Pattern TOKEN_PATTERN = Pattern.compile("\"(.*?)\"");
+---
+> private static final Pattern TOKEN_PATTERN = Pattern.compile("\\{\"token\": \"(.*?)\"\\}");
+89,92c89,90
+< final String group = matcher.group(0);
+< if (group.equalsIgnoreCase("token")) {
+< result.complete(group);
+< }
+---
+> final String group = matcher.group(1);
+> result.complete(group);
\ No newline at end of file
diff --git a/API/src/main/java/net/juligames/core/api/message/LegacyMessageType.java b/API/src/main/java/net/juligames/core/api/message/LegacyMessageType.java
index 70136dd5..82530833 100644
--- a/API/src/main/java/net/juligames/core/api/message/LegacyMessageType.java
+++ b/API/src/main/java/net/juligames/core/api/message/LegacyMessageType.java
@@ -5,22 +5,60 @@
import org.jetbrains.annotations.NotNull;
/**
- * @author Ture Bentzin
- * 25.02.2023
+ * The {@code LegacyMessageType} interface represents the types of formatting codes used in legacy Minecraft chat messages.
+ * These codes are used to change the color, formatting, and other properties of text in the chat.
+ *
+ * The {@code LegacyMessageType} interface provides two default implementations for commonly used formatting codes:
+ * {@link #AMPERSAND} and {@link #SECTION}. Additionally, custom formatting codes can be created using the static
+ * {@link #custom(char)} method.
+ *
+ *
Note that these formatting codes are only supported in legacy Minecraft versions. Modern Minecraft versions use
+ * JSON-formatted chat messages instead. You are still able to use them through Spigot but it is recommended to use
+ * Components instead
+ *
+ * @since 1.4
*/
@ApiStatus.AvailableSince("1.4")
public interface LegacyMessageType {
+
+ /**
+ * A {@code LegacyMessageType} implementation for the '&' formatting code.
+ */
@NotNull LegacyMessageType AMPERSAND = () -> '&';
+
+ /**
+ * A {@code LegacyMessageType} implementation for the '§' formatting code.
+ */
@NotNull LegacyMessageType SECTION = () -> '§';
+ /**
+ * Creates a custom {@code LegacyMessageType} implementation for the specified character.
+ *
+ * @param c the formatting code character
+ * @return a new {@code CustomLegacyMessageType} instance for the specified character
+ */
@Contract(pure = true)
static @NotNull CustomLegacyMessageType custom(char c) {
return new CustomLegacyMessageType(c);
}
+ /**
+ * Gets the formatting code character for this {@code LegacyMessageType}.
+ *
+ * @return the formatting code character
+ */
char getChar();
+ /**
+ * A {@code record} implementation of {@code LegacyMessageType} for custom formatting codes.
+ */
record CustomLegacyMessageType(char c) implements LegacyMessageType {
+
+ /**
+ * Gets the formatting code character for this {@code CustomLegacyMessageType}.
+ *
+ * @return the formatting code character
+ */
@Override
public char getChar() {
return c;
diff --git a/API/src/main/java/net/juligames/core/api/message/MessageApi.java b/API/src/main/java/net/juligames/core/api/message/MessageApi.java
index 89ddb624..b0583364 100644
--- a/API/src/main/java/net/juligames/core/api/message/MessageApi.java
+++ b/API/src/main/java/net/juligames/core/api/message/MessageApi.java
@@ -10,27 +10,58 @@
import java.util.Locale;
import java.util.stream.Stream;
+/*
+The MessageApi interface is a high-level API for sending messages to various recipients.
+It defines methods for sending single or multiple messages, with or without message key replacement, to either a single recipient or a collection of recipients.
+
+The interface defines two types of message sending methods: sendMessage and broadcastMessage.
+The sendMessage method is used to send a message to a single recipient, while the broadcastMessage method is used to send a message to multiple recipients.
+Both methods have several overloaded versions to accommodate different scenarios, such as sending messages with or without message key replacements, specifying the default or override locales, and so on.
+
+The MessageApi interface also provides two methods to retrieve the default locale, defaultLocale and defaultUtilLocale.
+These methods return the default locale as a string and a java.util.Locale object, respectively.
+
+Overall, the MessageApi interface is a powerful and flexible API for sending messages, suitable for a wide range of use cases.
+ */
+
/**
+ * Provides an api for accessing and managing messages and message
+ * replacements.
+ *
* @author Ture Bentzin
* 18.11.2022
- * @apiNote Please consider that the core your using may not support all the operations below. If a core should not
- * support one of the methods there are two options what could happen. First the core could automatically execute a similar
- * Method and print a warning. If this should not be possible then the Core will throw an {@link UnsupportedOperationException} with further
- * information on how to approach this issue.
+ * @apiNote Please consider that the core your using may not support all the
+ * operations below.
+ * If a core should not support one of the methods, there are two options for what could happen.
+ * First, the core could
+ * automatically execute a similar Method and print a warning.
+ * If this
+ * should not be possible, then the Core will throw an
+ * {@link UnsupportedOperationException} with further information on
+ * how to approach this issue.
*/
@SuppressWarnings("unused")
public interface MessageApi {
+ /**
+ * Returns an array from a varargs input.
+ *
+ * @param ts the input arguments
+ * @param the type of the array elements
+ * @return the array
+ */
@SafeVarargs
@ApiStatus.AvailableSince("1.5")
static T[] arrFromVargs(T... ts) {
return ts;
}
-
/**
- * This is an alias for {@link #arrFromVargs(Object[])}
+ * Alias for {@link #arrFromVargs(Object[])}.
*
+ * @param ts the input arguments
+ * @param the type of the array elements
+ * @return the array
* @apiNote You should import this method static!
*/
@SafeVarargs
@@ -39,217 +70,902 @@ static T[] repl(T... ts) {
return arrFromVargs(ts);
}
- //DAO
+ /**
+ * Calls a message DAO extension.
+ *
+ * @param extensionCallback the callback to call
+ * @param the return type of the callback
+ * @return the callback result
+ * @apiNote Internal use only.
+ */
@ApiStatus.Internal
@ApiStatus.Experimental
-
- @Nullable R callMessageExtension(@NotNull ExtensionCallback extensionCallback);
+ @Nullable R callMessageExtension(@NotNull ExtensionCallback extensionCallback);
+ /**
+ * Calls a locale DAO extension.
+ *
+ * @param extensionCallback the callback to call
+ * @param the return type of the callback
+ * @return the callback result
+ * @apiNote Internal use only.
+ * @since experimental
+ */
@ApiStatus.Internal
@ApiStatus.Experimental
-
- @Nullable R callLocaleExtension(@NotNull ExtensionCallback extensionCallback);
+ @Nullable R callLocaleExtension(@NotNull ExtensionCallback extensionCallback);
+ /**
+ * Calls an extension callback with a ReplacementDAO instance as the second argument.
+ *
+ * @param extensionCallback the extension callback to call
+ * @param the type of the return value
+ * @return the result of the extension callback, or null if the callback returns null
+ * @throws RuntimeException if the extension callback throws an exception
+ */
@ApiStatus.Internal
@ApiStatus.Experimental
-
- @Nullable R callReplacementExtension(@NotNull ExtensionCallback extensionCallback);
+ @Nullable R callReplacementExtension(@NotNull ExtensionCallback extensionCallback);
+ /**
+ * Calls an extension callback with a ReplacementTypeDAO instance as the second argument.
+ *
+ * @param extensionCallback the extension callback to call
+ * @param the type of the return value
+ * @return the result of the extension callback, or null if the callback returns null
+ * @throws RuntimeException if the extension callback throws an exception
+ */
@ApiStatus.Internal
@ApiStatus.Experimental
-
- @Nullable R callReplacementTypeExtension(@NotNull ExtensionCallback extensionCallback);
+ @Nullable R callReplacementTypeExtension(@NotNull ExtensionCallback extensionCallback);
+
//get
+
+ /**
+ * Returns the {@link Message} with the specified message key and locale. If there is no {@link Message} with the
+ * specified key and locale, a FallbackMessage is returned instead.
+ *
+ * @param messageKey the key of the message to retrieve.
+ * @param locale the locale of the message to retrieve.
+ * @return the {@link Message} with the specified key and locale, or a FallbackMessage if no such message exists.
+ */
@NotNull Message getMessage(@NotNull String messageKey, @NotNull Locale locale);
+ /**
+ * Returns the {@link Message} with the specified message key and locale, with placeholders replaced by the specified
+ * replacement strings. If there is no {@link Message} with the specified key and locale, a FallbackMessage is returned
+ * instead.
+ *
+ * @param messageKey the key of the message to retrieve.
+ * @param locale the locale of the message to retrieve.
+ * @param replacements the replacement strings to substitute into the message.
+ * @return the {@link Message} with the specified key and locale, or a FallbackMessage if no such message exists.
+ */
@NotNull Message getMessage(@NotNull String messageKey, @NotNull Locale locale, String... replacements);
+ /**
+ * Returns the {@link Message} with the specified message key and locale string. If there is no {@link Message} with the
+ * specified key and locale, a FallbackMessage is returned instead.
+ *
+ * @param messageKey the key of the message to retrieve.
+ * @param locale the locale string of the message to retrieve.
+ * @return the {@link Message} with the specified key and locale, or a FallbackMessage if no such message exists.
+ */
@NotNull Message getMessage(@NotNull String messageKey, @NotNull String locale);
+ /**
+ * Returns the {@link Message} with the specified message key and locale string, with placeholders replaced by the specified
+ * replacement strings. If there is no {@link Message} with the specified key and locale, a FallbackMessage is returned
+ * instead.
+ *
+ * @param messageKey the key of the message to retrieve.
+ * @param locale the locale string of the message to retrieve.
+ * @param replacements the replacement strings to substitute into the message.
+ * @return the {@link Message} with the specified key and locale, or a FallbackMessage if no such message exists.
+ */
@NotNull Message getMessage(@NotNull String messageKey, @NotNull String locale, String... replacements);
+
+ /**
+ * Returns the {@link Message} with the specified message key and locale string. If there is no {@link Message} with the
+ * specified key and locale, a FallbackMessage is returned instead.
+ *
+ * @param messageKey the key of the message to retrieve.
+ * @param dbLocale the locale string of the message to retrieve.
+ * @return the {@link Message} with the specified key and locale, or a FallbackMessage if no such message exists.
+ */
@NotNull Message getMessage(@NotNull String messageKey, @NotNull DBLocale dbLocale);
+ /**
+ * Returns the {@link Message} with the specified message key and locale string, with placeholders replaced by the specified
+ * replacement strings. If there is no {@link Message} with the specified key and locale, a FallbackMessage is returned
+ * instead.
+ *
+ * @param messageKey the key of the message to retrieve.
+ * @param dbLocale the locale string of the message to retrieve.
+ * @param replacements the replacement strings to substitute into the message.
+ * @return the {@link Message} with the specified key and locale, or a FallbackMessage if no such message exists.
+ */
@NotNull Message getMessage(@NotNull String messageKey, @NotNull DBLocale dbLocale, String... replacements);
+ /**
+ * Returns a collection of Messages from the MessageSystem that match the specified message key.
+ *
+ * @param messageKey the message key used to retrieve the messages
+ * @return a collection of messages that match the specified message key
+ */
@NotNull Collection getMessage(@NotNull String messageKey);
+ /**
+ * Returns a collection of Messages from the MessageSystem that match the specified message key with the
+ * specified replacements applied to each message.
+ *
+ * @param messageKey the message key used to retrieve the messages
+ * @param replacements the array of replacements to apply to the messages
+ * @return a collection of messages that match the specified message key with the replacements applied
+ */
@NotNull Collection getMessage(@NotNull String messageKey, String... replacements);
+
+ /**
+ * Retrieves the message from the MessageSystem using the specified key and locale. The locale is automatically selected
+ * based on the provided locale parameter.
+ *
+ * @param messageKey The key to retrieve the message.
+ * @param locale The locale to use for the message. Can be null.
+ * @return The message.
+ */
@NotNull Message getMessageSmart(@NotNull String messageKey, @Nullable Locale locale);
+ /**
+ * Retrieves the message from the MessageSystem using the specified key, locale, and replacements. The locale is
+ * automatically selected based on the provided locale parameter.
+ *
+ * @param messageKey The key to retrieve the message.
+ * @param locale The locale to use for the message. Can be null.
+ * @param replacements The values to replace the placeholders in the message.
+ * @return The message.
+ */
@NotNull Message getMessageSmart(@NotNull String messageKey, @Nullable Locale locale, String... replacements);
+ /**
+ * Retrieves the message from the MessageSystem using the specified key and locale. The locale is automatically selected
+ * based on the provided locale parameter.
+ *
+ * @param messageKey The key to retrieve the message.
+ * @param locale The locale to use for the message.
+ * @return The message.
+ */
@NotNull Message getMessageSmart(@NotNull String messageKey, @NotNull String locale);
+ /**
+ * Retrieves the message from the MessageSystem using the specified key, locale, and replacements. The locale is
+ * automatically selected based on the provided locale parameter.
+ *
+ * @param messageKey The key to retrieve the message.
+ * @param locale The locale to use for the message.
+ * @param replacements The values to replace the placeholders in the message.
+ * @return The message.
+ */
@NotNull Message getMessageSmart(@NotNull String messageKey, @NotNull String locale, String... replacements);
+ /**
+ * Retrieves the message from the MessageSystem using the specified key and locale. The locale is automatically selected
+ * based on the provided locale parameter.
+ *
+ * @param messageKey The key to retrieve the message.
+ * @param dbLocale The DBLocale to use for the message.
+ * @return The message.
+ */
@NotNull Message getMessageSmart(@NotNull String messageKey, @NotNull DBLocale dbLocale);
+ /**
+ * Retrieves the message from the MessageSystem using the specified key, locale, and replacements. The locale is
+ * automatically selected based on the provided locale parameter.
+ *
+ * @param messageKey The key to retrieve the message.
+ * @param dbLocale The DBLocale to use for the message.
+ * @param replacements The values to replace the placeholders in the message.
+ * @return The message.
+ */
@NotNull Message getMessageSmart(@NotNull String messageKey, @NotNull DBLocale dbLocale, String... replacements);
+
+ /**
+ * Returns all messages for the specified {@link Locale}.
+ *
+ * @param locale the {@code Locale} used to filter the messages
+ * @return a collection of all messages for the specified {@code Locale}, or an empty collection if none were found
+ */
@NotNull Collection getAllFromLocale(@NotNull Locale locale);
+ /**
+ * Returns all messages for the specified {@link Locale} with replacements applied.
+ *
+ * @param locale the {@code Locale} used to filter the messages
+ * @param replacements an optional list of replacements to apply to the messages
+ * @return a collection of all messages for the specified {@code Locale}, with replacements applied, or an empty collection if none were found
+ */
@NotNull Collection getAllFromLocale(@NotNull Locale locale, String... replacements);
+ /**
+ * Returns all messages for the specified locale code.
+ *
+ * @param locale the locale code used to filter the messages
+ * @return a collection of all messages for the specified locale code, or an empty collection if none were found
+ */
@NotNull Collection getAllFromLocale(@NotNull String locale);
+ /**
+ * Returns all messages for the specified locale code with replacements applied.
+ *
+ * @param locale the locale code used to filter the messages
+ * @param replacements an optional list of replacements to apply to the messages
+ * @return a collection of all messages for the specified locale code, with replacements applied, or an empty collection if none were found
+ */
@NotNull Collection getAllFromLocale(@NotNull String locale, String... replacements);
+ /**
+ * Returns all messages for the specified database locale.
+ *
+ * @param dbLocale the database locale used to filter the messages
+ * @return a collection of all messages for the specified database locale, or an empty collection if none were found
+ */
@NotNull Collection getAllFromLocale(@NotNull DBLocale dbLocale);
+ /**
+ * Returns all messages for the specified database locale with replacements applied.
+ *
+ * @param dbLocale the database locale used to filter the messages
+ * @param replacements an optional list of replacements to apply to the messages
+ * @return a collection of all messages for the specified database locale, with replacements applied, or an empty collection if none were found
+ */
@NotNull Collection getAllFromLocale(@NotNull DBLocale dbLocale, String... replacements);
+
+ /**
+ * Returns all messages in the message system.
+ * This method is experimental and may be removed or changed in a future release.
+ *
+ * @return A collection of all messages in the message system.
+ */
@ApiStatus.Experimental
- @NotNull
- Collection getAll();
+ @NotNull Collection getAll();
+ /**
+ * Returns all messages in the message system with the given replacements.
+ * This method is experimental and may be removed or changed in a future release.
+ *
+ * @param replacements The replacements for the messages.
+ * @return A collection of all messages in the message system with the given replacements.
+ */
@ApiStatus.Experimental
- @NotNull
- Collection getAll(String... replacements);
+ @NotNull Collection getAll(String... replacements);
+ /**
+ * Returns a stream of all the database messages in the message system.
+ * This method is internal and should not be used outside of the message system implementation.
+ *
+ * @return A stream of all the database messages in the message system.
+ */
@ApiStatus.Internal
- @NotNull
- Stream streamData();
+ @NotNull Stream streamData();
+
+ /**
+ * Returns a collection of all the replacers in the message system.
+ *
+ * @return a collection of all the replacers
+ */
@NotNull Collection getReplacers();
+
//register
+ /**
+ * Registers a message with the specified message key.
+ *
+ * @param messageKey the message key to register
+ * @deprecated This method is deprecated and should be avoided. Instead, use the {@link #registerMessage(String, String)}
+ * method to register a message with a defaultMiniMessage.
+ */
@Deprecated
void registerMessage(@NotNull String messageKey);
+ /**
+ * Registers a message with the specified message key and default mini message.
+ *
+ * @param messageKey the message key to register
+ * @param defaultMiniMessage the default mini message for the message (EN_US)
+ */
void registerMessage(@NotNull String messageKey, @NotNull String defaultMiniMessage);
/**
- * If you want to register a legacyMessage please use the provided method in the AdventureAPI
+ * Registers a third-party message with the specified message key, third-party message, and custom message dealer.
+ * If you want to register a legacy message, please use the provided method in the AdventureAPI.
*
- * @param messageKey the ley
- * @param thirdPartyMessage the input
- * @param dealer the dealer
+ * @param messageKey the message key to register
+ * @param thirdPartyMessage the third-party message to register (EN_US)
+ * @param dealer the custom message dealer to convert the third-party message to a message that can be handled
+ * by the message system
+ * @since 1.4
*/
@ApiStatus.AvailableSince("1.4")
void registerThirdPartyMessage(@NotNull String messageKey, @NotNull String thirdPartyMessage, @NotNull CustomMessageDealer dealer);
+
+ /**
+ * Checks if a message exists in EN_US for the given message key in the message system.
+ *
+ * @param messageKey the key of the message to check
+ * @return {@code true} if a message exists for the given key, otherwise {@code false}
+ */
boolean hasMessage(@NotNull String messageKey);
+ /**
+ * Checks if a message exists for the given message key and locale in the message system.
+ *
+ * @param messageKey the key of the message to check
+ * @param locale the locale of the message to check
+ * @return {@code true} if a message exists for the given key and locale, otherwise {@code false}
+ */
boolean hasMessage(@NotNull String messageKey, @NotNull String locale);
+ /**
+ * Checks if a message exists for the given message key and locale in the message system.
+ *
+ * @param messageKey the key of the message to check
+ * @param locale the locale of the message to check
+ * @return {@code true} if a message exists for the given key and locale, otherwise {@code false}
+ */
boolean hasMessage(@NotNull String messageKey, @NotNull Locale locale);
+ /**
+ * Checks if a message exists for the given message key and locale in the message system.
+ *
+ * @param messageKey the key of the message to check
+ * @param locale the locale of the message to check
+ * @return {@code true} if a message exists for the given key and locale, otherwise {@code false}
+ */
boolean hasMessage(@NotNull String messageKey, @NotNull DBLocale locale);
+
//send
+ /**
+ * Sends a message to the specified recipient and returns a {@link MessagePostScript} that contains details about
+ * the message that was sent. The best locale for the message is determined via the {@link MessageRecipient}.
+ *
+ * @param messageKey the key of the message to send.
+ * @param messageRecipient the recipient of the message.
+ * @return a {@link MessagePostScript} that contains details about the sent message.
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient);
+ /**
+ * Sends the message with the specified message key to the given message recipient using the provided override locale.
+ *
+ * @param messageKey the message key
+ * @param messageRecipient the recipient of the message
+ * @param overrideLocale the locale to use instead of the best available locale for the recipient
+ * @return a MessagePostScript providing details about the sent message
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient, @NotNull Locale overrideLocale);
+ /**
+ * Sends the message with the specified message key to the given message recipient using the provided override locale.
+ *
+ * @param messageKey the message key
+ * @param messageRecipient the recipient of the message
+ * @param overrideLocale the locale to use instead of the best available locale for the recipient as a string in the format of "language_country"
+ * @return a MessagePostScript providing details about the sent message
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient, @NotNull String overrideLocale);
+ /**
+ * Sends the message with the specified message key to the given message recipient using the provided override locale.
+ *
+ * @param messageKey the message key
+ * @param messageRecipient the recipient of the message
+ * @param overrideLocale the locale to use instead of the best available locale for the recipient
+ * @return a MessagePostScript providing details about the sent message
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient, @NotNull DBLocale overrideLocale);
+ /**
+ * Sends a message to all available recipients with the specified message key and default locale.
+ *
+ * @param messageKey the key of the message to be sent
+ * @param defaultLocale the default locale to be used for the message
+ * @return a {@link MultiMessagePostScript} describing the details of the messages sent
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull String messageKey, @NotNull Locale defaultLocale);
+ /**
+ * Sends a message to all available recipients with the specified message key and default locale.
+ *
+ * @param messageKey the key of the message to be sent
+ * @param defaultLocale the default locale to be used for the message
+ * @return a {@link MultiMessagePostScript} describing the details of the messages sent
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull String messageKey, @NotNull String defaultLocale);
+ /**
+ * Sends a message to all available recipients with the specified message key and default locale.
+ *
+ * @param messageKey the key of the message to be sent
+ * @param defaultLocale the default locale to be used for the message
+ * @return a {@link MultiMessagePostScript} describing the details of the messages sent
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull String messageKey, @NotNull DBLocale defaultLocale);
+
+ /**
+ * Sends the message with the given {@code messageKey} to all available recipients and returns the
+ * {@link Collection} of {@link MessagePostScript}s containing details about each sent message.
+ *
+ * @param messageKey the key of the message to send
+ * @return a {@link Collection} of {@link MessagePostScript}s containing details about each sent message
+ */
@NotNull Collection broadcastMessage(@NotNull String messageKey);
+
+ /**
+ * Sends multiple messages to the same recipient.
+ *
+ * @param messageKeys the collection of message keys to send
+ * @param messageRecipient the recipient of the messages
+ * @return the post-script describing the details of the messages sent
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient);
+ /**
+ * Sends multiple messages to multiple recipients.
+ *
+ * @param messageKeys the collection of message keys to send
+ * @param messageRecipients the collection of recipients of the messages
+ * @return the post-script describing the details of the messages sent
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients);
+
+ /**
+ * Sends multiple messages to the same recipient with the given locale override.
+ *
+ * @param messageKeys the collection of message keys
+ * @param messageRecipient the message recipient
+ * @param overrideLocale the locale override
+ * @return the MultiMessagePostScript representing the sent messages
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient, @NotNull String overrideLocale);
+ /**
+ * Sends multiple messages to the same recipient with the given locale override.
+ *
+ * @param messageKeys the collection of message keys
+ * @param messageRecipient the message recipient
+ * @param overrideLocale the locale override
+ * @return the MultiMessagePostScript representing the sent messages
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient, @NotNull Locale overrideLocale);
+ /**
+ * Sends multiple messages to the same recipient with the given locale override.
+ *
+ * @param messageKeys the collection of message keys
+ * @param messageRecipient the message recipient
+ * @param overrideLocale the locale override
+ * @return the MultiMessagePostScript representing the sent messages
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient, @NotNull DBLocale overrideLocale);
- @NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, @NotNull String overrideLocale);
+ /**
+ * Sends a message composed of the given message keys to the specified message recipient, using the specified locale
+ * to override the default locale set in the recipient.
+ *
+ * @param messageKeys the collection of message keys to compose the message
+ * @param messageRecipients the collection of message recipients to send the message to
+ * @param overrideLocale the locale to use for message translation, overriding the recipient's default locale
+ * @return a MultiMessagePostScript containing details about the messages that were sent
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, @NotNull Locale overrideLocale);
+ /**
+ * Sends a message composed of the given message keys to the specified message recipient, using the specified DBLocale
+ * to override the default locale set in the recipient.
+ *
+ * @param messageKeys the collection of message keys to compose the message
+ * @param messageRecipients the collection of message recipients to send the message to
+ * @param overrideLocale the DBLocale to use for message translation, overriding the recipient's default locale
+ * @return a MultiMessagePostScript containing details about the messages that were sent
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, @NotNull DBLocale overrideLocale);
+ /**
+ * Sends a message composed of the given message keys to the specified message recipient, using the specified locale
+ * code (e.g. "EN_US") to override the default locale set in the recipient.
+ *
+ * @param messageKeys the collection of message keys to compose the message
+ * @param messageRecipients the collection of message recipients to send the message to
+ * @param overrideLocale the locale code to use for message translation, overriding the recipient's default locale
+ * @return a MultiMessagePostScript containing details about the messages that were sent
+ */
+ @NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, @NotNull String overrideLocale);
+
+ /**
+ * Sends the given messages to the given recipients, replacing any placeholders in the messages with the given replacements.
+ * The locale for each message is determined based on the locale of the recipient.
+ *
+ * @param messageKeys the keys of the messages to send
+ * @param messageRecipients the recipients to send the messages to
+ * @param replacement the replacements to use for any placeholders in the messages
+ * @return a collection of MultiMessagePostScript objects describing the messages that were sent
+ */
@NotNull Collection sendMessageSmart(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, String... replacement);
+ /**
+ * Sends the message with the given message key to the specified collection of recipients.
+ *
+ * @param messageKey the message key
+ * @param messageRecipients the collection of message recipients
+ * @return a collection of {@link MessagePostScript} objects describing the details of each message sent
+ */
@NotNull Collection sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients);
+ /**
+ * Sends a message with the given message key to a collection of message recipients with an overridden locale.
+ *
+ * @param messageKey The message key to use.
+ * @param messageRecipients The collection of message recipients to send the message to.
+ * @param overrideLocale The locale to use instead of the recipients' default locale.
+ * @return A MultiMessagePostScript containing details about the sent messages.
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients, @NotNull String overrideLocale);
+ /**
+ * Sends a message with the given message key to a collection of message recipients with an overridden locale.
+ *
+ * @param messageKey The message key to use.
+ * @param messageRecipients The collection of message recipients to send the message to.
+ * @param overrideLocale The locale to use instead of the recipients' default locale.
+ * @return A MultiMessagePostScript containing details about the sent messages.
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients, @NotNull Locale overrideLocale);
+ /**
+ * Sends a message with the given message key to a collection of message recipients with an overridden locale.
+ *
+ * @param messageKey The message key to use.
+ * @param messageRecipients The collection of message recipients to send the message to.
+ * @param overrideLocale The locale to use instead of the recipients' default locale.
+ * @return A MultiMessagePostScript containing details about the sent messages.
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients, @NotNull DBLocale overrideLocale);
+ /**
+ * Sends a message with the given message key and replacements to the specified recipients.
+ *
+ * @param messageKey the message key for the message to be sent
+ * @param messageRecipients the recipients to send the message to
+ * @param replacements replacements to be made in the message
+ * @return a collection of {@code MessagePostScript} objects representing the details of the sent messages
+ */
@NotNull Collection sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients, String... replacements);
+ /**
+ * Sends a message with the given message key, replacements, and locale override to the specified recipients.
+ *
+ * @param messageKey the message key for the message to be sent
+ * @param messageRecipients the recipients to send the message to
+ * @param overrideLocale the locale to use for the message, overriding any default locale
+ * @param replacements replacements to be made in the message
+ * @return a {@code MultiMessagePostScript} object representing the details of the sent messages
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients, @NotNull String overrideLocale, String... replacements);
+ /**
+ * Sends a message with the given message key, replacements, and locale override to the specified recipients.
+ *
+ * @param messageKey the message key for the message to be sent
+ * @param messageRecipients the recipients to send the message to
+ * @param overrideLocale the locale to use for the message, overriding any default locale
+ * @param replacements replacements to be made in the message
+ * @return a {@code MultiMessagePostScript} object representing the details of the sent messages
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients, @NotNull Locale overrideLocale, String... replacements);
- @NotNull MultiMessagePostScript sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients, @NotNull DBLocale overrideLocale, String... replacements);
-
+ /**
+ * Sends a message with a specific message key to a collection of message recipients,
+ * with the option to override the default locale for message retrieval.
+ *
+ * @param messageKey the key for the message to be sent
+ * @param messageRecipients the collection of message recipients to receive the message
+ * @param overrideLocale the locale to use for message retrieval, overriding the default locale
+ * @param replacements the replacement values to be used in the message, if any
+ * @return the post-script for the message sending operation
+ */
+ @NotNull
+ MultiMessagePostScript sendMessage(@NotNull String messageKey, @NotNull Collection messageRecipients,
+ @NotNull DBLocale overrideLocale, String... replacements);
+ /**
+ * Sends the specified message to multiple recipients with the specified default locale.
+ *
+ * @param messageKeys a collection of keys of the messages to be sent
+ * @param defaultLocale the default locale for the messages
+ * @return a {@link MultiMessagePostScript} object representing the result of the messages sent
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys, @NotNull Locale defaultLocale);
+ /**
+ * Sends the specified message to multiple recipients with the specified default locale.
+ *
+ * @param messageKeys a collection of keys of the messages to be sent
+ * @param defaultLocale the default locale for the messages
+ * @return a {@link MultiMessagePostScript} object representing the result of the messages sent
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys, @NotNull String defaultLocale);
+ /**
+ * Sends the specified message to multiple recipients with the specified default locale.
+ *
+ * @param messageKeys a collection of keys of the messages to be sent
+ * @param defaultLocale the default locale for the messages
+ * @return a {@link MultiMessagePostScript} object representing the result of the messages sent
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys, @NotNull DBLocale defaultLocale);
+ /**
+ * Sends the specified message to multiple recipients with the default locale.
+ *
+ * @param messageKeys a collection of keys of the messages to be sent
+ * @return a {@link MultiMessagePostScript} object representing the result of the messages sent
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys);
- //sending with replacements
+ /**
+ * Sends a message with replacement values to a single recipient.
+ *
+ * @param messageKey The key identifying the message to send.
+ * @param messageRecipient The recipient to send the message to.
+ * @param replacement The replacement values to use in the message.
+ * @return A {@code MessagePostScript} object representing the sent message.
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient, String... replacement);
+ /**
+ * Sends a message with replacement values to a single recipient, overriding the locale of the message.
+ *
+ * @param messageKey The key identifying the message to send.
+ * @param messageRecipient The recipient to send the message to.
+ * @param overrideLocale The locale to use for the message, overriding the default locale.
+ * @param replacement The replacement values to use in the message.
+ * @return A {@code MessagePostScript} object representing the sent message.
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient, @NotNull Locale overrideLocale, String... replacement);
+ /**
+ * Sends a message with replacement values to a single recipient, overriding the locale of the message.
+ *
+ * @param messageKey The key identifying the message to send.
+ * @param messageRecipient The recipient to send the message to.
+ * @param overrideLocale The locale to use for the message, overriding the default locale.
+ * @param replacement The replacement values to use in the message.
+ * @return A {@code MessagePostScript} object representing the sent message.
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient, @NotNull String overrideLocale, String... replacement);
+ /**
+ * Sends a message with replacement values to a single recipient, overriding the locale of the message.
+ *
+ * @param messageKey The key identifying the message to send.
+ * @param messageRecipient The recipient to send the message to.
+ * @param overrideLocale The locale to use for the message, overriding the default locale.
+ * @param replacement The replacement values to use in the message.
+ * @return A {@code MessagePostScript} object representing the sent message.
+ */
@NotNull MessagePostScript sendMessage(@NotNull String messageKey, @NotNull MessageRecipient messageRecipient, @NotNull DBLocale overrideLocale, String... replacement);
+
+ /**
+ * Broadcasts a message with the given key to all message recipients, using the given default locale and replacements.
+ *
+ * @param messageKey the key of the message to be broadcasted
+ * @param defaultLocale the default locale to use for the broadcast
+ * @param replacement optional replacements for placeholders in the message
+ * @return a multi-message post script containing the status of each sent message
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull String messageKey, @NotNull Locale defaultLocale, String... replacement);
+ /**
+ * Broadcasts a message with the given key to all message recipients, using the given default locale and replacements.
+ *
+ * @param messageKey the key of the message to be broadcasted
+ * @param defaultLocale the default locale to use for the broadcast
+ * @param replacement optional replacements for placeholders in the message
+ * @return a multi-message post script containing the status of each sent message
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull String messageKey, @NotNull String defaultLocale, String... replacement);
+ /**
+ * Broadcasts a message with the given key to all message recipients, using the given default locale and replacements.
+ *
+ * @param messageKey the key of the message to be broadcasted
+ * @param defaultLocale the default locale to use for the broadcast
+ * @param replacement optional replacements for placeholders in the message
+ * @return a multi-message post script containing the status of each sent message
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull String messageKey, @NotNull DBLocale defaultLocale, String... replacement);
+
+ /**
+ * Sends a message with replacements to all recipients, using the default locale.
+ *
+ * @param messageKey the key for the message to send
+ * @param replacement the replacements for placeholders in the message
+ * @return a collection of message post-scripts for each recipient
+ */
@NotNull Collection broadcastMessage(@NotNull String messageKey, String... replacement);
+
+ /**
+ * Sends a collection of messages to a single message recipient with optional replacements.
+ *
+ * @param messageKeys the collection of message keys to be sent
+ * @param messageRecipient the message recipient to send the messages to
+ * @param replacement optional replacement strings to be used in the message templates
+ * @return the postscript representing the sending of the messages
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient, String... replacement);
/**
- * @deprecated use {@link MessageApi#sendMessageSmart(Collection, Collection, String...)} instead
+ * @param messageKeys The keys of the messages to send.
+ * @param messageRecipients The recipients of the messages.
+ * @param replacement The replacements for message placeholders.
+ * @return A {@link MultiMessagePostScript} object containing the result of the message sending operation.
+ * @deprecated Use {@link MessageApi#sendMessageSmart(Collection, Collection, String...)} instead.
*/
@Deprecated
- @NotNull
- MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, String... replacement);
+ @NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, String... replacement);
+ /**
+ * Sends a message to a single recipient with the specified locale override and replacement values.
+ *
+ * @param messageKeys The keys of the messages to send.
+ * @param messageRecipient The recipient of the message.
+ * @param overrideLocale The locale to use instead of the recipient's locale.
+ * @param replacement The replacements for message placeholders.
+ * @return A {@link MultiMessagePostScript} object containing the result of the message sending operation.
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient, @NotNull String overrideLocale, String... replacement);
+ /**
+ * Sends a message to the given message recipient(s) with the specified message keys and replacements.
+ *
+ * @param messageKeys the collection of message keys to send
+ * @param messageRecipient the message recipient to send the messages to
+ * @param overrideLocale the locale to use when sending the message(s)
+ * @param replacement the array of message replacement values to use when sending the message(s)
+ * @return the message post-script
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient, @NotNull Locale overrideLocale, String... replacement);
+ /**
+ * Sends a message to the given message recipient(s) with the specified message keys and replacements.
+ *
+ * @param messageKeys the collection of message keys to send
+ * @param messageRecipient the message recipient to send the messages to
+ * @param overrideLocale the DB locale to use when sending the message(s)
+ * @param replacement the array of message replacement values to use when sending the message(s)
+ * @return the message post-script
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull MessageRecipient messageRecipient, @NotNull DBLocale overrideLocale, String... replacement);
+ /**
+ * Sends a message to the given message recipient(s) with the specified message keys and replacements.
+ *
+ * @param messageKeys the collection of message keys to send
+ * @param messageRecipients the collection of message recipients to send the messages to
+ * @param overrideLocale the locale to use when sending the message(s)
+ * @param replacement the array of message replacement values to use when sending the message(s)
+ * @return the collection of message post-scripts
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, @NotNull String overrideLocale, String... replacement);
+ /**
+ * Sends a collection of messages with replacements to a collection of message recipients, with the specified locale override.
+ *
+ * @param messageKeys the collection of message keys to send
+ * @param messageRecipients the collection of message recipients to send the messages to
+ * @param overrideLocale the locale override to use for the messages
+ * @param replacement the array of replacements to use for each message
+ * @return a {@link MultiMessagePostScript} representing the post-script of the messages sent
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, @NotNull Locale overrideLocale, String... replacement);
+ /**
+ * Sends a collection of messages with replacements to a collection of message recipients, with the specified DB locale override.
+ *
+ * @param messageKeys the collection of message keys to send
+ * @param messageRecipients the collection of message recipients to send the messages to
+ * @param overrideLocale the DB locale override to use for the messages
+ * @param replacement the array of replacements to use for each message
+ * @return a {@link MultiMessagePostScript} representing the post-script of the messages sent
+ */
@NotNull MultiMessagePostScript sendMessage(@NotNull Collection messageKeys, @NotNull Collection messageRecipients, @NotNull DBLocale overrideLocale, String... replacement);
+ /**
+ * Sends a message broadcast to all recipients with the given message keys and replacement values.
+ *
+ * @param messageKeys the message keys to send.
+ * @param defaultLocale the default locale to use if a specific locale is not specified.
+ * @param replacement the replacement values to use in the message.
+ * @return a {@code MultiMessagePostScript} object representing the result of the operation.
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys, @NotNull Locale defaultLocale, String... replacement);
+ /**
+ * Sends a message broadcast to all recipients with the given message keys and replacement values.
+ *
+ * @param messageKeys the message keys to send.
+ * @param defaultLocale the default locale to use if a specific locale is not specified.
+ * @param replacement the replacement values to use in the message.
+ * @return a {@code MultiMessagePostScript} object representing the result of the operation.
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys, @NotNull String defaultLocale, String... replacement);
+ /**
+ * Sends a message broadcast to all recipients with the given message keys and replacement values.
+ *
+ * @param messageKeys the message keys to send.
+ * @param defaultLocale the default locale to use if a specific locale is not specified.
+ * @param replacement the replacement values to use in the message.
+ * @return a {@code MultiMessagePostScript} object representing the result of the operation.
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys, @NotNull DBLocale defaultLocale, String... replacement);
+ /**
+ * Sends a message broadcast to all recipients with the given message keys and replacement values.
+ *
+ * @param messageKeys the message keys to send.
+ * @param replacement the replacement values to use in the message.
+ * @return a {@code MultiMessagePostScript} object representing the result of the operation.
+ */
@NotNull MultiMessagePostScript broadcastMessage(@NotNull Collection messageKeys, String... replacement);
+
+ /**
+ * @param messageKey the messageKey
+ * @param messageRecipient the recipient
+ * @return the best locale
+ * @deprecated use {@link MessageApi#findBestMessageForRecipient(String, MessageRecipient)} instead
+ */
+ @Deprecated
+ @ApiStatus.AvailableSince("1.6")
+ String findBestForRecipient(String messageKey, @NotNull MessageRecipient messageRecipient);
+
+ @ApiStatus.AvailableSince("1.6")
+ Message findBestMessageForRecipient(String messageKey, @NotNull MessageRecipient messageRecipient);
+
+ @ApiStatus.AvailableSince("1.6")
+ Message findBestMessageForRecipient(String messageKey, @NotNull MessageRecipient messageRecipient, String... replacements);
+
+ /**
+ * Returns the default locale (EN_US) as a String.
+ *
+ * @return the default locale as a String
+ */
@NotNull String defaultLocale();
+ /**
+ * Returns the default locale (EN_US) as a Locale object.
+ *
+ * @return the default locale as a Locale object
+ */
@NotNull Locale defaultUtilLocale();
+
//TagManager getTagManager(); removed in favor of AdventureCore / AdventureAPI
}
diff --git a/API/src/main/java/net/juligames/core/api/message/MessagePostScript.java b/API/src/main/java/net/juligames/core/api/message/MessagePostScript.java
index 6334e297..a83421ba 100644
--- a/API/src/main/java/net/juligames/core/api/message/MessagePostScript.java
+++ b/API/src/main/java/net/juligames/core/api/message/MessagePostScript.java
@@ -11,22 +11,32 @@
public interface MessagePostScript {
/**
+ * Gets the message that was sent.
+ *
* @return the message that was sent (this may be not the exact message)
*/
@NotNull Message message();
/**
+ * Gets the time the message was sent.
+ *
* @return the time (not exact - do not use for encryption) the message sending was complete
*/
@NotNull Date timeSent();
/**
+ * Gets the recipient of the message.
+ *
* @return the recipient of the message
*/
@NotNull MessageRecipient recipient();
/**
- * @return transfer this {@link MessagePostScript} to a {@link MultiMessagePostScript}
+ * Converts this {@link MessagePostScript} to a {@link MultiMessagePostScript}.
+ *
+ * @return the {@link MultiMessagePostScript} representation of this object
*/
@NotNull MultiMessagePostScript toMulti();
}
+
+
diff --git a/API/src/main/java/net/juligames/core/api/message/MessageRecipient.java b/API/src/main/java/net/juligames/core/api/message/MessageRecipient.java
index 996f6066..3fafc43f 100644
--- a/API/src/main/java/net/juligames/core/api/message/MessageRecipient.java
+++ b/API/src/main/java/net/juligames/core/api/message/MessageRecipient.java
@@ -6,40 +6,56 @@
import org.jetbrains.annotations.Nullable;
/**
+ * The MessageRecipient interface defines the methods necessary for an object to receive a message.
+ *
* @author Ture Bentzin
* 18.11.2022
*/
public interface MessageRecipient {
/**
- * @return A human-readable name that defines this recipient
+ * Returns a human-readable name that defines this recipient.
+ *
+ * @return a human-readable name that defines this recipient
*/
@NotNull String getName();
/**
- * Delivers the specified Message to this MessageRecipient. The message should always be human-readable!
+ * Delivers the specified message to this MessageRecipient. The message should always be human-readable.
*
* @param message the message to deliver
*/
void deliver(@NotNull Message message);
-
/**
- * delivers a miniMessage string to the recipient
+ * Returns the locale of this MessageRecipient, or null if the locale is not specified.
+ *
+ * @return the locale of this MessageRecipient, or null if the locale is not specified
*/
- @ApiStatus.Internal
- @Deprecated
- void deliver(@NotNull String miniMessage);
-
- @Nullable
- String supplyLocale();
+ @Nullable String supplyLocale();
/**
- * This will return the default locale that is distributed by the master
+ * Returns the default locale that is distributed by the master, or the locale of this MessageRecipient if
+ * specified.
+ *
+ * @return the default locale that is distributed by the master, or the locale of this MessageRecipient if
+ * specified
*/
default @Nullable String supplyLocaleOrDefault() {
- if (supplyLocale() != null) return supplyLocale();
+ if (supplyLocale() != null) {
+ return supplyLocale();
+ }
return API.get().getHazelDataApi().getMasterInformation().get("default_locale");
}
+ /**
+ * @param miniMessage the miniMessage string to deliver
+ * @deprecated Use {@link #deliver(Message)} instead.
+ *
+ * Delivers a miniMessage string to the recipient.
+ */
+ @Deprecated
+ @ApiStatus.Internal
+ void deliver(@NotNull String miniMessage);
+
}
diff --git a/API/src/main/java/net/juligames/core/api/message/MiniMessageSerializer.java b/API/src/main/java/net/juligames/core/api/message/MiniMessageSerializer.java
index 6387762c..1fa43613 100644
--- a/API/src/main/java/net/juligames/core/api/message/MiniMessageSerializer.java
+++ b/API/src/main/java/net/juligames/core/api/message/MiniMessageSerializer.java
@@ -3,51 +3,66 @@
import org.jetbrains.annotations.NotNull;
/**
+ * This interface provides methods for serializing a MiniMessage to plain text or legacy format.
+ * It also provides methods for translating legacy format messages to MiniMessage format.
+ *
* @author Ture Bentzin
* 25.12.2022
*/
public interface MiniMessageSerializer {
/**
- * This will resolve the given message to a plain String. This will strip all colors and decorations!
+ * This method resolves the given message to a plain text string, stripping all colors and decorations.
*
- * @param message the message
- * @return plain text
+ * @param message the MiniMessage to resolve
+ * @return a plain text string representation of the MiniMessage
*/
@NotNull
String resolvePlain(@NotNull Message message);
/**
- * This will resolve the given message to a "legacy format String". This will remove all advanced decorations!
+ * This method resolves the given message to a legacy format string, removing all advanced decorations.
*
- * @param message the message
- * @return legacy message
+ * @param message the MiniMessage to resolve
+ * @return a legacy format string representation of the MiniMessage
*/
@Deprecated
@NotNull
String resolveLegacy(@NotNull Message message);
/**
- * This will resolve the given message to a plain String. This will strip all colors and decorations!
+ * This method resolves the given miniMessage to a plain text string, stripping all colors and decorations.
*
- * @param miniMessage the message
- * @return plain text
+ * @param miniMessage the miniMessage to resolve
+ * @return a plain text string representation of the miniMessage
*/
@Deprecated
@NotNull
String resolvePlain(@NotNull String miniMessage);
/**
- * This will resolve the given message to a "legacy format String". This will remove all advanced decorations!
+ * This method resolves the given miniMessage to a legacy format string, removing all advanced decorations.
*
- * @param miniMessage the message
- * @return legacy message
+ * @param miniMessage the miniMessage to resolve
+ * @return a legacy format string representation of the miniMessage
*/
@Deprecated
@NotNull
String resolveLegacy(@NotNull String miniMessage);
+ /**
+ * This method translates a legacy format string to MiniMessage format.
+ *
+ * @param ampersand the legacy format string to translate
+ * @return a MiniMessage format string representation of the legacy format string
+ */
@NotNull String translateLegacyToMiniMessage(@NotNull String ampersand);
+ /**
+ * This method translates a legacy format section string to MiniMessage format.
+ *
+ * @param section the legacy format section string to translate
+ * @return a MiniMessage format string representation of the legacy format section string
+ */
@NotNull String translateLegacySectionToMiniMessage(@NotNull String section);
}
diff --git a/API/src/main/java/net/juligames/core/api/message/PatternType.java b/API/src/main/java/net/juligames/core/api/message/PatternType.java
index fc61d9ce..6c2f2af2 100644
--- a/API/src/main/java/net/juligames/core/api/message/PatternType.java
+++ b/API/src/main/java/net/juligames/core/api/message/PatternType.java
@@ -1,53 +1,97 @@
+/**
+ * The PatternType enum represents the different types of patterns that can be used
+ * to identify placeholders in messages. The enum includes information about the
+ * start and end characters of the pattern, a tag identifier for the pattern,
+ * and whether the pattern should be resolved.
+ *
+ * @author Ture Bentzin
+ * @since 11.02.2023
+ */
package net.juligames.core.api.message;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
-/**
- * @author Ture Bentzin
- * 11.02.2023
- */
public enum PatternType {
+ // Enum constants
UNTRUSTED('{', '}', "safe", false),
TRUSTED('[', ']', "unsafe", true);
-
+ // Fields
private final char start;
private final char end;
private final String tagIdentifier;
private final boolean resolve;
- PatternType(char start, char end, String tagIdentifier, boolean parse) {
+ // Constructor
+ PatternType(char start, char end, String tagIdentifier, boolean resolve) {
this.start = start;
this.end = end;
this.tagIdentifier = tagIdentifier;
- this.resolve = parse;
+ this.resolve = resolve;
}
+ // Methods - why is this so EXTREME javadoced?
+
+ /**
+ * Builds a pattern string using the start and end characters and an integer index.
+ *
+ * @param i the integer index to use in the pattern
+ * @return the pattern string
+ */
@Contract(pure = true)
public @NotNull String buildPattern(int i) {
return String.valueOf(start) + i + end;
}
+ /**
+ * Builds a tag string using the tag identifier and an integer index.
+ *
+ * @param i the integer index to use in the tag
+ * @return the tag string
+ */
@Contract(pure = true)
public @NotNull String buildTag(int i) {
return "<" + buildTagID(i) + ">";
}
+ /**
+ * Builds a tag identifier string using the tag identifier and an integer index.
+ *
+ * @param i the integer index to use in the tag identifier
+ * @return the tag identifier string
+ */
@Contract(pure = true)
public @NotNull String buildTagID(int i) {
return "param_" + tagIdentifier + "_" + i;
}
+ /**
+ * Converts a pattern string to a tag string.
+ *
+ * @param target the target string to convert
+ * @param index the integer index to use in the tag
+ * @return the converted tag string
+ */
public @NotNull String convertPatternToTag(@NotNull String target, int index) {
return target.replace(buildPattern(index), buildTag(index));
}
+ /**
+ * Returns whether or not the pattern should be resolved.
+ *
+ * @return true if the pattern should be resolved, false otherwise
+ */
public boolean shouldParse() {
return resolve;
}
+ /**
+ * Returns a string representation of the PatternType enum constant.
+ *
+ * @return a string representation of the PatternType enum constant
+ */
@Contract(pure = true)
public @NotNull String toString() {
return "PatternType: " + name() + ": \"" + start + "i" + end + "\"";
diff --git a/API/src/main/java/net/juligames/core/api/minigame/StartType.java b/API/src/main/java/net/juligames/core/api/minigame/StartType.java
index 60c621cd..e61c93f7 100644
--- a/API/src/main/java/net/juligames/core/api/minigame/StartType.java
+++ b/API/src/main/java/net/juligames/core/api/minigame/StartType.java
@@ -11,19 +11,63 @@
@ApiStatus.AvailableSince("1.5")
public interface StartType {
+ /**
+ * The direct starting option.
+ */
StartType DIRECT = new SimpleStartType("DIRECT");
+
+ /**
+ * The delayed starting option.
+ */
StartType DELAYED = new SimpleStartType("DELAYED");
+ /**
+ * Compares two StartType objects for similarity.
+ *
+ * @param s1 the first StartType object
+ * @param s2 the second StartType object
+ * @return true if the objects are similar, false otherwise
+ */
static boolean compare(@NotNull StartType s1, StartType s2) {
return s1.isSimilar(s2);
}
+ /**
+ * Returns the name of this StartType object.
+ *
+ * @return the name of this StartType object
+ */
String getName();
+ /**
+ * Checks whether this StartType object is similar to another StartType object.
+ *
+ *
+ * Two StartType objects are considered similar if they have the same name.
+ *
+ *
+ * @param startType the StartType object to compare to
+ * @return true if the objects are similar, false otherwise
+ *
+ * Example usage:
+ * {@code
+ * StartType s1 = StartType.DIRECT;
+ * StartType s2 = new SimpleStartType("DIRECT");
+ * boolean areSimilar = s1.isSimilar(s2); // true
+ *
+ * StartType s3 = new ImaginaryStartType("IMAGINARY");
+ * StartType s4 = new SimpleStartType("IMAGINARY");
+ * boolean areSimilar2 = s3.isSimilar(s4); // true
+ * }
+ */
default boolean isSimilar(@NotNull StartType startType) {
return this.getName().equals(startType.getName());
}
+
+ /**
+ * A simple implementation of the StartType interface.
+ */
record SimpleStartType(String name) implements StartType {
@Override
public String getName() {
diff --git a/API/src/main/java/net/juligames/core/api/misc/APIUtils.java b/API/src/main/java/net/juligames/core/api/misc/APIUtils.java
new file mode 100644
index 00000000..9af23098
--- /dev/null
+++ b/API/src/main/java/net/juligames/core/api/misc/APIUtils.java
@@ -0,0 +1,176 @@
+package net.juligames.core.api.misc;
+
+import de.bentzin.tools.Independent;
+import de.bentzin.tools.logging.JavaLogger;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.*;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import java.util.logging.Logger;
+import java.util.stream.Stream;
+
+/**
+ * @author Ture Bentzin
+ * 10.04.2023
+ */
+@ApiStatus.AvailableSince("1.6")
+public class APIUtils {
+
+ private APIUtils() {
+
+ }
+
+ /**
+ * Formats a StackFrame object to obtain caller information.
+ *
+ * @param frame The StackFrame object representing the caller.
+ * @return A formatted string containing caller information.
+ */
+ @Independent
+ public static @NotNull String formatCaller(StackWalker.@NotNull StackFrame frame) {
+ return frame.getMethodName()
+ + "@"
+ + frame.getClassName()
+ + ":" + frame.getLineNumber()
+ + (frame.getClassName().equals(frame.getFileName())
+ ? " "
+ : " located in " + frame.getFileName() + "[" + frame.getByteCodeIndex() + "]");
+ }
+
+ /**
+ * Executes the given `ThrowingRunnable` and returns `true` if it completes without throwing an exception, or if the thrown exception is not contained in the specified collection of exceptions.
+ *
+ * @param runnable the `ThrowingRunnable` to execute
+ * @param exceptions a collection of exceptions that should not be counted as a failure
+ * @return `true` if the `ThrowingRunnable` completes without throwing an exception or if the thrown exception is not contained in the specified collection of exceptions
+ */
+ @Independent
+ public static boolean executedWithoutException(@NotNull ThrowingRunnable runnable, @NotNull Collection exceptions) {
+ try {
+ runnable.run();
+ return true;
+ } catch (Exception e) {
+ return !exceptions.contains(e);
+ }
+ }
+
+ /**
+ * Executes the given `ThrowingRunnable` and returns `true` if it completes without throwing an exception.
+ *
+ * @param runnable the `ThrowingRunnable` to execute
+ * @return `true` if the `ThrowingRunnable` completes without throwing an exception
+ */
+ @Independent
+ public static boolean executedWithoutException(@NotNull ThrowingRunnable runnable) {
+ return executedWithoutException(runnable, Collections.emptyList());
+ }
+
+ /**
+ * Executes the given `ThrowingRunnable` and returns `true` if it completes without throwing an exception that is contained in the specified array of exceptions.
+ *
+ * @param runnable the `ThrowingRunnable` to execute
+ * @param exceptions an array of exceptions that should not be counted as a failure
+ * @return `true` if the `ThrowingRunnable` completes without throwing an exception or if the thrown exception is not contained in the specified array of exceptions
+ */
+ @Independent
+ public static boolean executedWithoutException(@NotNull ThrowingRunnable runnable, Exception... exceptions) {
+ return executedWithoutException(runnable, List.of(exceptions));
+ }
+
+ /**
+ * Executes the given `Runnable` and returns `true` if it completes without throwing an exception, or if the thrown exception is not contained in the specified collection of exceptions.
+ *
+ * @param runnable the `Runnable` to execute
+ * @param exceptions a collection of exceptions that should not be counted as a failure
+ * @return `true` if the `Runnable` completes without throwing an exception or if the thrown exception is not contained in the specified collection of exceptions
+ */
+ @Independent
+ public static boolean executedWithoutExceptionL(@NotNull Runnable runnable, @NotNull Collection exceptions) {
+ try {
+ runnable.run();
+ return true;
+ } catch (Exception e) {
+ return !exceptions.contains(e);
+ }
+ }
+
+ /**
+ * Executes the given `Runnable` and returns `true` if it completes without throwing an exception.
+ *
+ * @param runnable the `Runnable` to execute
+ * @return `true` if the `Runnable` completes without throwing an exception
+ */
+ @Independent
+ public static boolean executedWithoutExceptionL(@NotNull Runnable runnable) {
+ return executedWithoutExceptionL(runnable, Collections.emptyList());
+ }
+
+ /**
+ * Maps the elements of the input stream using the provided mapper function, while dropping any elements that cause an exception during mapping.
+ *
+ * @param the type of the input stream elements
+ * @param the type of the resulting stream elements
+ * @param stream the input stream to be mapped
+ * @param mapper the mapping function to apply to each element of the input stream
+ * @return a new stream containing the mapped elements, with any elements causing an exception during mapping dropped
+ */
+ @Independent
+ public static @NotNull Stream mapOrDrop(@NotNull Stream stream, @NotNull Function mapper) {
+ List list = new ArrayList<>();
+ stream.forEachOrdered(t -> {
+ try {
+ list.add(mapper.apply(t));
+ } catch (Exception ignored) {
+ // drop
+ }
+ });
+ return list.stream();
+ }
+
+ public static void executeAndSwallow(ThrowingRunnable throwingRunnable) {
+ try {
+ throwingRunnable.run();
+ } catch (Exception ignored) {
+ }
+ }
+
+ @SafeVarargs
+ public static Optional executeAndReturnFirstSuccess(Supplier @NotNull ... suppliers) {
+ for (Supplier supplier : suppliers) {
+ try {
+ return Optional.of(supplier.get());
+ } catch (Exception ignore) {
+ }
+ }
+ return Optional.empty();
+ }
+
+ /**
+ * Creates a JavaLogger instance from a {@link Logger}.
+ *
+ * @param logger The {@link Logger} instance.
+ * @return A {@link JavaLogger} instance.
+ */
+ @Contract("_ -> new")
+ @Independent
+ public static @NotNull JavaLogger fromUtil(Logger logger) {
+ return new JavaLogger(logger.getName(), logger);
+ }
+
+ /**
+ * Creates a JavaLogger instance from a logger name.
+ *
+ * @param name The name of the logger.
+ * @return A {@link JavaLogger} instance.
+ */
+ @Contract("_ -> new")
+ @Independent
+ public static @NotNull JavaLogger fromName(String name) {
+ return fromUtil(Logger.getLogger(name));
+ }
+
+
+}
diff --git a/API/src/main/java/net/juligames/core/api/misc/DurationFormatUtils.java b/API/src/main/java/net/juligames/core/api/misc/DurationFormatUtils.java
index 6285d582..df83d4f9 100644
--- a/API/src/main/java/net/juligames/core/api/misc/DurationFormatUtils.java
+++ b/API/src/main/java/net/juligames/core/api/misc/DurationFormatUtils.java
@@ -22,7 +22,6 @@
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.text.StrBuilder;
import org.apache.commons.lang.time.DateUtils;
-import org.checkerframework.checker.units.qual.A;
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
@@ -78,6 +77,26 @@ public class DurationFormatUtils {
static final @NotNull Object S = "S";
public static @NotNull String INTERNAL_MESSAGE_PREFIX = "internal.api.misc.format.";
+ static {
+ API.get().getAPILogger().info(DurationFormatUtils.class.getName() + " was loaded! Trying to register default messages:");
+ long s1 = System.currentTimeMillis();
+ try {
+ registerMessages();
+ //BIT
+ final long between = s1 - System.currentTimeMillis();
+ Duration duration = Duration.ofMillis(between);
+ String formatDurationWords = formatDurationWords(duration, false, false, null,
+ API.get().getMessageApi().defaultUtilLocale());
+ API.get().getAPILogger().info("finished registration of default messages! (took: " + formatDurationWords + ")");
+ } catch (Exception e) {
+ API.get().getAPILogger().warning("failed to register default messages: " + e);
+ ThrowableDebug.debug(e);
+ }
+
+ }
+
+ //-----------------------------------------------------------------------
+
/**
* DurationFormatUtils instances should NOT be constructed in standard programming.
*
@@ -88,8 +107,6 @@ public DurationFormatUtils() {
super();
}
- //-----------------------------------------------------------------------
-
/**
* Formats the time gap as a string.
*
@@ -245,24 +262,6 @@ public DurationFormatUtils() {
suppressTrailingZeroElements, getLocalisationFromMessageSystem(locale, s));
}
- static {
- API.get().getAPILogger().info(DurationFormatUtils.class.getName() + " was loaded! Trying to register default messages:");
- long s1 = System.currentTimeMillis();
- try {
- registerMessages();
- //BIT
- final long between = s1 - System.currentTimeMillis();
- Duration duration = Duration.ofMillis(between);
- String formatDurationWords = formatDurationWords(duration, false, false, null,
- API.get().getMessageApi().defaultUtilLocale());
- API.get().getAPILogger().info("finished registration of default messages! (took: " + formatDurationWords + ")");
- }catch (Exception e){
- API.get().getAPILogger().error("failed to register default messages: " + e);
- ThrowableDebug.debug(e);
- }
-
- }
-
public static void registerMessages() {
registerDefaultMessage("days");
registerDefaultMessage("hours");
@@ -669,7 +668,7 @@ static Token[] lexx(String format) {
Object value = null;
switch (ch) {
// TODO: Need to handle escaping of '
- case '\'':
+ case '\'' -> {
if (inLiteral) {
buffer = null;
inLiteral = false;
@@ -678,34 +677,21 @@ static Token[] lexx(String format) {
list.add(new Token(buffer));
inLiteral = true;
}
- break;
- case 'y':
- value = y;
- break;
- case 'M':
- value = M;
- break;
- case 'd':
- value = d;
- break;
- case 'H':
- value = H;
- break;
- case 'm':
- value = m;
- break;
- case 's':
- value = s;
- break;
- case 'S':
- value = S;
- break;
- default:
+ }
+ case 'y' -> value = y;
+ case 'M' -> value = M;
+ case 'd' -> value = d;
+ case 'H' -> value = H;
+ case 'm' -> value = m;
+ case 's' -> value = s;
+ case 'S' -> value = S;
+ default -> {
if (buffer == null) {
buffer = new StringBuffer();
list.add(new Token(buffer));
}
buffer.append(ch);
+ }
}
if (value != null) {
@@ -719,7 +705,7 @@ static Token[] lexx(String format) {
buffer = null;
}
}
- return (Token[]) list.toArray(new Token[list.size()]);
+ return (Token[]) list.toArray(new Token[0]);
}
diff --git a/API/src/main/java/net/juligames/core/api/misc/EntryInterpretationUtil.java b/API/src/main/java/net/juligames/core/api/misc/EntryInterpretationUtil.java
index d16c6d75..f5bf9c77 100644
--- a/API/src/main/java/net/juligames/core/api/misc/EntryInterpretationUtil.java
+++ b/API/src/main/java/net/juligames/core/api/misc/EntryInterpretationUtil.java
@@ -1,36 +1,80 @@
package net.juligames.core.api.misc;
import net.juligames.core.api.config.Interpreter;
+import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Unmodifiable;
import java.util.Collection;
import java.util.Map;
+import java.util.function.IntFunction;
import java.util.stream.Collectors;
+@ApiStatus.AvailableSince("1.5")
public class EntryInterpretationUtil {
private EntryInterpretationUtil() {
}
+ /**
+ * Interpret an entry in a {@link Map} using the given key and value interpreters and return an unmodifiable map entry.
+ *
+ * @param stringStringEntry the map entry to interpret
+ * @param kInterpreter the key interpreter
+ * @param vInterpreter the value interpreter
+ * @param the type of the key
+ * @param the type of the value
+ * @return an unmodifiable map entry with an interpreted key and value
+ * @throws Exception if there is an error during interpretation
+ */
@Contract("_, _, _ -> new")
public static Map.@NotNull @Unmodifiable Entry interpretEntry(Map.@NotNull Entry stringStringEntry, @NotNull Interpreter kInterpreter, @NotNull Interpreter vInterpreter) throws Exception {
return Map.entry(kInterpreter.interpret(stringStringEntry.getKey()), vInterpreter.interpret(stringStringEntry.getValue()));
}
+ /**
+ * Reverse an entry in a {@link Map} using the given key and value interpreters and return an unmodifiable map entry.
+ *
+ * @param stringStringEntry the map entry to reverse
+ * @param kInterpreter the key interpreter
+ * @param vInterpreter the value interpreter
+ * @param the type of the key
+ * @param the type of the value
+ * @return an unmodifiable map entry with reversed key and value
+ */
@Contract("_, _, _ -> new")
public static Map.@NotNull @Unmodifiable Entry reverseEntry(Map.@NotNull Entry stringStringEntry, @NotNull Interpreter kInterpreter, @NotNull Interpreter vInterpreter) {
return Map.entry(kInterpreter.reverse(stringStringEntry.getKey()), vInterpreter.reverse(stringStringEntry.getValue()));
}
- public static @Unmodifiable Collection> reverseEntries(@NotNull Collection> collection, Interpreter kInterpreter, Interpreter vInterpreter) {
+ /**
+ * Reverse a collection of entries in a {@link Map} using the given key and value interpreters and return an unmodifiable collection of map entries.
+ *
+ * @param collection the collection of map entries to reverse
+ * @param kInterpreter the key interpreter
+ * @param vInterpreter the value interpreter
+ * @param the type of the key
+ * @param the type of the value
+ * @return an unmodifiable collection of map entries with reversed key and value
+ */
+ public static @NotNull @Unmodifiable Collection> reverseEntries(@NotNull Collection> collection, @NotNull Interpreter kInterpreter, @NotNull Interpreter vInterpreter) {
return collection.stream().map(kvEntry -> reverseEntry(kvEntry, kInterpreter, vInterpreter)).collect(Collectors.toUnmodifiableSet());
}
-
- public static @Unmodifiable Collection> interpretEntries(@NotNull Collection> collection, Interpreter kInterpreter, Interpreter vInterpreter) {
+ /**
+ * Interpret a collection of entries in a {@link Map} using the given key and value interpreters and return an unmodifiable collection of map entries.
+ *
+ * @param collection the collection of map entries to interpret
+ * @param kInterpreter the key interpreter
+ * @param vInterpreter the value interpreter
+ * @param the type of the key
+ * @param the type of the value
+ * @return an unmodifiable collection of map entries with interpreted key and value
+ * @throws RuntimeException if there is an error during interpretation
+ */
+ public static @NotNull @Unmodifiable Collection> interpretEntries(@NotNull Collection> collection, @NotNull Interpreter kInterpreter, @NotNull Interpreter vInterpreter) {
return collection.stream().map(kvEntry -> {
try {
return interpretEntry(kvEntry, kInterpreter, vInterpreter);
@@ -39,4 +83,13 @@ private EntryInterpretationUtil() {
}
}).collect(Collectors.toUnmodifiableSet());
}
+
+ public static @Unmodifiable @NotNull Map interpretMap(@NotNull Map map, @NotNull Interpreter kInterpreter, @NotNull Interpreter vInterpreter) {
+ return Map.ofEntries(interpretEntries(map.entrySet(), kInterpreter, vInterpreter).toArray((IntFunction[]>) value -> new Map.Entry[0]));
+ }
+
+ public static @Unmodifiable @NotNull Map reverseMap(@NotNull Map map, @NotNull Interpreter kInterpreter, @NotNull Interpreter vInterpreter) {
+ return Map.ofEntries(reverseEntries(map.entrySet(), kInterpreter, vInterpreter).toArray((IntFunction[]>) value -> new Map.Entry[0]));
+ }
+
}
diff --git a/API/src/main/java/net/juligames/core/api/misc/GenericHashtableToStringHashtableMapper.java b/API/src/main/java/net/juligames/core/api/misc/GenericHashtableToStringHashtableMapper.java
index 614977bf..d29f992e 100644
--- a/API/src/main/java/net/juligames/core/api/misc/GenericHashtableToStringHashtableMapper.java
+++ b/API/src/main/java/net/juligames/core/api/misc/GenericHashtableToStringHashtableMapper.java
@@ -9,6 +9,10 @@
import java.util.function.Function;
/**
+ * The GenericHashtableToStringHashtableMapper class is a function that maps a Hashtable with generic key-value types
+ * to a Hashtable with String keys and String values.
+ * It uses provided interpreters to convert the keys and values of the input Hashtable to their String representations.
+ *
* @author Ture Bentzin
* 03.03.2023
*/
@@ -18,16 +22,39 @@ public class GenericHashtableToStringHashtableMapper implements Function kInterpreter;
private final @NotNull Interpreter vInterpreter;
+ /**
+ * Constructs a GenericHashtableToStringHashtableMapper with the given key and value interpreters.
+ *
+ * @param kInterpreter the interpreter for converting keys to String
+ * @param vInterpreter the interpreter for converting values to String
+ * @throws NullPointerException if the kInterpreter or vInterpreter parameter is null
+ */
public GenericHashtableToStringHashtableMapper(@NotNull Interpreter kInterpreter, @NotNull Interpreter vInterpreter) {
this.kInterpreter = kInterpreter;
this.vInterpreter = vInterpreter;
}
+ /**
+ * Creates a new GenericHashtableToStringHashtableMapper with a parallel interpreter for keys and values of the same type.
+ *
+ * @param the type of the keys and values
+ * @param tInterpreter the interpreter for converting keys and values to String
+ * @return a GenericHashtableToStringHashtableMapper with parallel key and value interpreters
+ * @throws NullPointerException if the tInterpreter parameter is null
+ */
@Contract(value = "_ -> new", pure = true)
public static @NotNull GenericHashtableToStringHashtableMapper createParallel(final Interpreter tInterpreter) {
return new GenericHashtableToStringHashtableMapper<>(tInterpreter, tInterpreter);
}
+ /**
+ * Applies the mapping function to the given input Hashtable, converting its keys and values to String
+ * and creating a new Hashtable with String keys and String values.
+ *
+ * @param objectObjectHashtable the input Hashtable to be mapped
+ * @return a new Hashtable with String keys and String values
+ * @throws NullPointerException if the objectObjectHashtable parameter is null
+ */
@Override
public @NotNull Hashtable apply(@NotNull Hashtable objectObjectHashtable) {
final Hashtable stringStringHashtable = new Hashtable<>();
@@ -35,4 +62,4 @@ public GenericHashtableToStringHashtableMapper(@NotNull Interpreter kInterpre
stringStringHashtable.put(kInterpreter.reverse(key), vInterpreter.reverse(value)));
return stringStringHashtable;
}
-}
+}
\ No newline at end of file
diff --git a/API/src/main/java/net/juligames/core/api/misc/Predicates.java b/API/src/main/java/net/juligames/core/api/misc/Predicates.java
new file mode 100644
index 00000000..0f5fa0f0
--- /dev/null
+++ b/API/src/main/java/net/juligames/core/api/misc/Predicates.java
@@ -0,0 +1,53 @@
+package net.juligames.core.api.misc;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.function.Consumer;
+import java.util.function.Predicate;
+
+/**
+ * This class provides predicates
+ *
+ * @author Ture Bentzin
+ * 19.05.2023
+ * @implNote might use {@link APIUtils#executedWithoutExceptionL(Runnable)} later
+ */
+public class Predicates {
+
+ private Predicates() {
+
+ }
+
+ @Contract(pure = true)
+ @ApiStatus.AvailableSince("1.6")
+ public static @NotNull Predicate instanceOf(Class clazz) {
+ return t -> t.getClass().isInstance(clazz);
+ }
+
+ @Contract(pure = true)
+ @ApiStatus.AvailableSince("1.6")
+ public static @NotNull Predicate nestedIn(Class clazz) {
+ return t -> t.getClass().getNestHost().equals(clazz);
+ }
+
+ @Contract(pure = true)
+ @ApiStatus.AvailableSince("1.6")
+ public static @NotNull Predicate executes(Consumer operation) {
+ return t -> {
+ try {
+ operation.accept(t);
+ } catch (Exception e) {
+ return false;
+ }
+ return true;
+ };
+ }
+
+ @Contract(pure = true)
+ @ApiStatus.AvailableSince("1.6")
+ public static @NotNull Predicate fails(Consumer operation) {
+ return Predicate.not(executes(operation));
+ }
+}
diff --git a/API/src/main/java/net/juligames/core/api/misc/ThrowableDebug.java b/API/src/main/java/net/juligames/core/api/misc/ThrowableDebug.java
index e00d4c16..834d5e5c 100644
--- a/API/src/main/java/net/juligames/core/api/misc/ThrowableDebug.java
+++ b/API/src/main/java/net/juligames/core/api/misc/ThrowableDebug.java
@@ -1,7 +1,6 @@
package net.juligames.core.api.misc;
import net.juligames.core.api.API;
-import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull;
import java.io.PrintWriter;
diff --git a/API/src/main/java/net/juligames/core/api/misc/ThrowingRunnable.java b/API/src/main/java/net/juligames/core/api/misc/ThrowingRunnable.java
new file mode 100644
index 00000000..20966f71
--- /dev/null
+++ b/API/src/main/java/net/juligames/core/api/misc/ThrowingRunnable.java
@@ -0,0 +1,20 @@
+package net.juligames.core.api.misc;
+
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Like a normal {@link Runnable} but it accepts Exceptions
+ *
+ * @author Ture Bentzin
+ * 10.04.2023
+ */
+public interface ThrowingRunnable {
+
+ @Contract(pure = true)
+ static @NotNull ThrowingRunnable fromRunnable(@NotNull Runnable runnable) {
+ return runnable::run;
+ }
+
+ void run() throws Exception;
+}
diff --git a/AdventureAPI/pom.xml b/AdventureAPI/pom.xml
index a183bb67..1331fef7 100644
--- a/AdventureAPI/pom.xml
+++ b/AdventureAPI/pom.xml
@@ -1,12 +1,18 @@
+
JuliGamesCore
net.juligames.core
- 1.5
+ 1.6
4.0.0
@@ -24,7 +30,7 @@
net.juligames.core
API
- 1.5
+ 1.6
@@ -45,6 +51,11 @@
4.11.0
compile
+
+ de.bentzin
+ ConversationLib
+ 1.3.1
+
\ No newline at end of file
diff --git a/AdventureAPI/src/main/java/net/juligames/core/adventure/AdventureTagManager.java b/AdventureAPI/src/main/java/net/juligames/core/adventure/AdventureTagManager.java
index 703b2d8d..4b14ba28 100644
--- a/AdventureAPI/src/main/java/net/juligames/core/adventure/AdventureTagManager.java
+++ b/AdventureAPI/src/main/java/net/juligames/core/adventure/AdventureTagManager.java
@@ -49,6 +49,7 @@ public interface AdventureTagManager extends MiniMessageSerializer {
/**
* This method creates a new {@link TagResolver} that combines {@link #getResolver()} and append
+ *
* @param append additional resolvers
* @return a new {@link TagResolver}
*/
diff --git a/AdventureAPI/src/main/java/net/juligames/core/adventure/api/AdventureAPI.java b/AdventureAPI/src/main/java/net/juligames/core/adventure/api/AdventureAPI.java
index 0ddd9055..16f188dd 100644
--- a/AdventureAPI/src/main/java/net/juligames/core/adventure/api/AdventureAPI.java
+++ b/AdventureAPI/src/main/java/net/juligames/core/adventure/api/AdventureAPI.java
@@ -18,7 +18,7 @@
* Please make sure the modules (AdventureAPI & AdventureCore) are the same version to avoid issues while execution!
*/
public interface AdventureAPI {
- @NotNull String API_VERSION = "1.5";
+ @NotNull String API_VERSION = "1.6";
static @NotNull AdventureAPI get() {
AdventureAPI api = AdventureAPICore.getAPI();
diff --git a/AdventureAPI/src/main/java/net/juligames/core/adventure/api/MessageRepresentation.java b/AdventureAPI/src/main/java/net/juligames/core/adventure/api/MessageRepresentation.java
new file mode 100644
index 00000000..f449c5f4
--- /dev/null
+++ b/AdventureAPI/src/main/java/net/juligames/core/adventure/api/MessageRepresentation.java
@@ -0,0 +1,99 @@
+package net.juligames.core.adventure.api;
+
+import net.juligames.core.adventure.AdventureTagManager;
+import net.juligames.core.api.API;
+import net.juligames.core.api.config.representations.Representation;
+import net.juligames.core.api.jdbi.DBLocale;
+import net.juligames.core.api.message.Message;
+import net.kyori.adventure.identity.Identity;
+import net.kyori.adventure.pointer.Pointered;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.ComponentLike;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Locale;
+
+/**
+ * @author Ture Bentzin
+ * 25.03.2023
+ */
+@ApiStatus.AvailableSince("1.6")
+public class MessageRepresentation implements ComponentLike, Representation {
+
+ private final @NotNull AdventureTagManager adventureTagManager;
+ private final @NotNull Message message;
+
+ public MessageRepresentation(@NotNull AdventureTagManager adventureTagManager, @NotNull Message message) {
+ this.adventureTagManager = adventureTagManager;
+ this.message = message;
+ }
+
+ public MessageRepresentation(@NotNull Message message) {
+ this.adventureTagManager = AdventureAPI.get().getAdventureTagManager();
+ this.message = message;
+ }
+
+ @Contract("_, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, String locale) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey, locale));
+ }
+
+ @Contract("_, _, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, String locale, String... replacements) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey, locale, replacements));
+ }
+
+ @Contract("_, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, Locale locale) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey, locale));
+ }
+
+ @Contract("_, _, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, Locale locale, String... replacements) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey, locale, replacements));
+ }
+
+ @Contract("_, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, DBLocale locale) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey, locale));
+ }
+
+ @Contract("_, _, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, DBLocale locale, String... replacements) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey, locale, replacements));
+ }
+
+ //Personal
+
+ @Contract("_, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, @NotNull Pointered pointered) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey,
+ pointered.get(Identity.LOCALE).orElse(defaultLocale())));
+ }
+
+ @Contract("_, _, _ -> new")
+ public static @NotNull MessageRepresentation represent(String messageKey, @NotNull Pointered pointered, String... replacements) {
+ return new MessageRepresentation(API.get().getMessageApi().getMessageSmart(messageKey, pointered.get(Identity.LOCALE).orElse(defaultLocale()), replacements));
+ }
+
+ private static @NotNull Locale defaultLocale() {
+ return API.get().getMessageApi().defaultUtilLocale();
+ }
+
+ @Override
+ public @NotNull Component asComponent() {
+ return adventureTagManager.resolve(message);
+ }
+
+ public Message getMessage() {
+ return message;
+ }
+
+ @Override
+ @ApiStatus.AvailableSince("1.6")
+ public Component represent() {
+ return asComponent();
+ }
+}
diff --git a/AdventureAPI/src/main/java/net/juligames/core/adventure/api/interpreter/IndexBackedInterpreterProvider.java b/AdventureAPI/src/main/java/net/juligames/core/adventure/api/interpreter/IndexBackedInterpreterProvider.java
new file mode 100644
index 00000000..16ba8dbb
--- /dev/null
+++ b/AdventureAPI/src/main/java/net/juligames/core/adventure/api/interpreter/IndexBackedInterpreterProvider.java
@@ -0,0 +1,164 @@
+package net.juligames.core.adventure.api.interpreter;
+
+import net.juligames.core.api.config.Interpreter;
+import net.kyori.adventure.util.Index;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.NoSuchElementException;
+import java.util.function.Supplier;
+
+/**
+ * The `IndexBackedInterpreterProvider` class is an implementation of the `Supplier` interface that provides an interpreter for a given index-based data source.
+ * It allows interpreting values based on keys and vice versa, using two different interpreters for key and value types.
+ * The interpretation can be done in the normal direction or in an inverted direction, depending on the `inverted` flag.
+ *
+ * @param The type of the keys in the index.
+ * @param The type of the values in the index.
+ * @param The type of the index that implements the `Index` interface.
+ * @author Ture Bentzin
+ * 18.05.2023
+ * @apiNote You can use {@link IndexBackedInterpreterProviderBuilder} to build your instance
+ */
+@ApiStatus.AvailableSince("1.6")
+public final class IndexBackedInterpreterProvider> implements Supplier> {
+
+ private final Interpreter normalInterpreter;
+ private final Interpreter invertedInterpreter;
+ private final Index source;
+ private final boolean inverted;
+
+ /**
+ * Creates a new `IndexBackedInterpreterProvider` with the provided key and value interpreters and data source.
+ * The interpretation is set to be in the normal direction (non-inverted).
+ *
+ * @param kInterpreter The interpreter for the key type `K`.
+ * @param vInterpreter The interpreter for the value type `V`.
+ * @param source The data source to pull from, implementing the `Index` interface.
+ */
+ public IndexBackedInterpreterProvider(Interpreter kInterpreter, Interpreter vInterpreter, Index source) {
+ this(kInterpreter, vInterpreter, source, false);
+ }
+
+ /**
+ * Creates a new `IndexBackedInterpreterProvider` with the provided key and value interpreters, data source, and inversion flag.
+ *
+ * @param kInterpreter The interpreter for the key type `K`.
+ * @param vInterpreter The interpreter for the value type `V`.
+ * @param source The data source to pull from, implementing the `Index` interface.
+ * @param inverted Flag indicating whether the interpretation is inverted or not.
+ */
+ public IndexBackedInterpreterProvider(Interpreter kInterpreter, Interpreter vInterpreter, Index source, boolean inverted) {
+ this.source = source;
+ this.inverted = inverted;
+
+ // Create the normal interpreter
+ this.normalInterpreter = new Interpreter<>() {
+ /**
+ * Interprets the given input as a value and retrieves it from the source.
+ *
+ * @param input The input to interpret.
+ * @return The interpreted value.
+ * @throws Exception if an error occurs during interpretation or value retrieval.
+ */
+ @Override
+ public @NotNull V interpret(String input) throws Exception {
+ return getSource().valueOrThrow(kInterpreter.interpret(input));
+ }
+
+ /**
+ * Reverses the interpretation by converting the value back to its corresponding key.
+ *
+ * @param v The value to reverse.
+ * @return The reversed key as a string.
+ * @throws NoSuchElementException If the key corresponding to the value is not found in the index.
+ */
+ @Override
+ public @NotNull String reverse(V v) throws NoSuchElementException {
+ try {
+ return kInterpreter.reverse(getSource().keyOrThrow(v));
+ } catch (NoSuchElementException e) {
+ throw new NoSuchElementException("Key not found for the provided value.");
+ }
+ }
+ };
+
+ // Create the inverted interpreter
+ this.invertedInterpreter = new Interpreter<>() {
+ /**
+ * Interprets the given input as a key and retrieves the corresponding value from the source.
+ *
+ * @param input The input to interpret.
+ * @return The interpreted key.
+ * @throws Exception if an error occurs during interpretation or key retrieval.
+ */
+ @Override
+ public @NotNull K interpret(String input) throws Exception {
+ return getSource().keyOrThrow(vInterpreter.interpret(input));
+ }
+
+ /**
+ * Reverses the interpretation by converting the key back to its corresponding value.
+ *
+ * @param k The key to reverse.
+ * @return The reversed value as a string.
+ * @throws NoSuchElementException If the value corresponding to the key is not found in the index.
+ */
+ @Override
+ public @NotNull String reverse(K k) throws NoSuchElementException {
+ try {
+ return vInterpreter.reverse(getSource().valueOrThrow(k));
+ } catch (NoSuchElementException e) {
+ throw new NoSuchElementException("Value not found for the provided key.");
+ }
+ }
+
+ };
+ }
+
+ /**
+ * Retrieves the data source associated with this interpreter provider.
+ *
+ * @return The index-based data source.
+ */
+ public Index getSource() {
+ return source;
+ }
+
+ /**
+ * Returns the interpreter to use based on the inversion flag.
+ *
+ * @return The interpreter instance.
+ */
+ @Override
+ public Interpreter get() {
+ return !inverted ? normalInterpreter : invertedInterpreter;
+ }
+
+ /**
+ * Retrieves the inverted interpreter.
+ *
+ * @return The interpreter for inverted interpretation.
+ */
+ public Interpreter