diff --git a/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStats.java b/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStats.java index 1693830..14dda5e 100644 --- a/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStats.java +++ b/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStats.java @@ -1,6 +1,7 @@ package com.gmail.artemis.the.gr8.playerstats.api; import com.gmail.artemis.the.gr8.playerstats.Main; +import net.kyori.adventure.platform.bukkit.BukkitAudiences; import net.kyori.adventure.text.TextComponent; import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer; import org.bukkit.Material; @@ -9,19 +10,25 @@ import org.bukkit.entity.EntityType; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; -/** This Interface is the outgoing API that provides access to the core functionality of PlayerStats. - To work with it, you can call PlayerStats.{@link #getAPI()} to get an instance of {@link PlayerStatsAPI}. - You can then use this object to get formatted statistics. - -

Since calculating a top or server statistics can take some time, it is recommended to call any of the +/** This is the outgoing API that you can use to access the core functionality of PlayerStats. + To work with it, you need to call PlayerStats.{@link #getAPI()} to get an instance of {@link PlayerStatsAPI}. + You can then use this object to access any of the further methods. +
+
Since calculating a top or server statistics can take some time, it is recommended to call all the getServerStat() or getTopStats() methods asynchronously. Otherwise, the main Thread will have - to wait until all calculations are done, and this might cause lag spikes on the server.

- -

The result of the methods in PlayerStats' API are returned in the form of a TextComponent, - which can be sent directly to a Minecraft client with the Adventure library, - or turned into a String with {@link #statResultComponentToString(TextComponent)}. - Don't use the Adventure method .content() on your result instead of the method specified in here - - because of the way the TextComponent is built by PlayerStats, you won't be able to get the full content that way.

*/ + to wait until all calculations are done, and this might cause some lag spikes on the server. +
+
The result of the methods in PlayerStats' API are returned in the form of a TextComponent, + which can be sent directly to a Minecraft client or console with the Adventure library. + To send a Component, you need to get a {@link BukkitAudiences} object. Normally you would + have to add the library as a dependency, but since the library is included in PlayerStats, you can + access it directly. Information on how to get and use the BukkitAudiences object can be found on + Adventure's website. +
+
Alternatively, you can also turn your TextComponent into a plain String with + {@link #statResultComponentToString(TextComponent)}. Don't use Adventure's method .content() + on your statResult to do this - because of the way the TextComponent is built by PlayerStats, + you won't be able to get the full content that way.

*/ public interface PlayerStats { /** Returns an instance of the {@link PlayerStatsAPI}. @@ -33,35 +40,71 @@ public interface PlayerStats { /** Turns a TextComponent into its String representation. If you don't want to work with Adventure's TextComponents, you can call this method to turn any stat-result into a String. - It will lose all color and style, but it will keep line-breaks.*/ + @return a String representation of this TextComponent, without color and style, but with line-breaks*/ default String statResultComponentToString(TextComponent statResult) { return PlainTextComponentSerializer.plainText().serialize(statResult); } - /** Get a formatted player-statistic of Statistic.Type UNTYPED.*/ - TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws IllegalArgumentException; + /** Get a formatted player-statistic of Statistic.Type UNTYPED. + @return a TextComponent with the following parts: +
[player-name]: [number] [stat-name] + @throws NullPointerException if statistic or playerName is null*/ + TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws NullPointerException; - /** Get a formatted player-statistic of Statistic.Type BLOCK or ITEM.*/ - TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws IllegalArgumentException; + /** Get a formatted player-statistic of Statistic.Type BLOCK or ITEM. + @return a TextComponent with the following parts: +
[player-name]: [number] [stat-name] [sub-stat-name] + @throws NullPointerException if statistic, material or playerName is null*/ + TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws NullPointerException; - /** Get a formatted player-statistic of Statistic.Type ENTITY.*/ - TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws IllegalArgumentException; + /** Get a formatted player-statistic of Statistic.Type ENTITY. + @return a TextComponent with the following parts: +
[player-name]: [number] [stat-name] [sub-stat-name] + @throws NullPointerException if statistic, entity or playerName is null*/ + TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws NullPointerException; - /** Get a formatted server-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description).*/ - TextComponent getServerStat(@NotNull Statistic statistic) throws IllegalArgumentException; + /** Get a formatted server-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description). + @return a TextComponent with the following parts: +
[Total on] [server-name]: [number] [stat-name] + @throws NullPointerException if statistic is null*/ + TextComponent getServerStat(@NotNull Statistic statistic) throws NullPointerException; - /** Get a formatted server-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description).*/ - TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException; + /** Get a formatted server-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description). + @return a TextComponent with the following parts: +
[Total on] [server-name]: [number] [stat-name] [sub-stat-name] + @throws NullPointerException if statistic or material is null*/ + TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException; - /** Get a formatted server-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description).*/ - TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException; + /** Get a formatted server-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description). + @return a TextComponent with the following parts: +
[Total on] [server-name]: [number] [stat-name] [sub-stat-name] + @throws NullPointerException if statistic or entity is null*/ + TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException; - /** Get a formatted top-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description).*/ - TextComponent getTopStats(@NotNull Statistic statistic) throws IllegalArgumentException; + /** Get a formatted top-statistic of Statistic.Type UNTYPED. Not recommended to call this from the main Thread (see class description). + @return a TextComponent with the following parts: +
[PlayerStats] [Top 10] [stat-name] +
[1.] [player-name] [number] +
[2.] [player-name] [number] +
[3.] etc... + @throws NullPointerException if statistic is null*/ + TextComponent getTopStats(@NotNull Statistic statistic) throws NullPointerException; - /** Get a formatted top-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description).*/ - TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException; + /** Get a formatted top-statistic of Statistic.Type BLOCK or ITEM. Not recommended to call this from the main Thread (see class description). + @return a TextComponent with the following parts: +
[PlayerStats] [Top 10] [stat-name] [sub-stat-name] +
[1.] [player-name] [number] +
[2.] [player-name] [number] +
[3.] etc... + @throws NullPointerException if statistic or material is null*/ + TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException; - /** Get a formatted top-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description).*/ - TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException; + /** Get a formatted top-statistic of Statistic.Type ENTITY. Not recommended to call this from the main Thread (see class description). + @return a TextComponent with the following parts: +
[PlayerStats] [Top 10] [stat-name] [sub-stat-name] +
[1.] [player-name] [number] +
[2.] [player-name] [number] +
[3.] etc... + @throws NullPointerException if statistic or entity is null*/ + TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException; } \ No newline at end of file diff --git a/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStatsAPI.java b/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStatsAPI.java index 3bc3e11..43c7ce8 100644 --- a/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStatsAPI.java +++ b/src/main/java/com/gmail/artemis/the/gr8/playerstats/api/PlayerStatsAPI.java @@ -31,52 +31,52 @@ public final class PlayerStatsAPI implements PlayerStats { } @Override - public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws IllegalArgumentException { + public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull String playerName) throws NullPointerException { return getFormattedStatistic(Target.PLAYER, statistic, null, null, playerName); } @Override - public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws IllegalArgumentException { + public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull Material material, @NotNull String playerName) throws NullPointerException { return getFormattedStatistic(Target.PLAYER, statistic, material, null, playerName); } @Override - public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws IllegalArgumentException { + public TextComponent getPlayerStat(@NotNull Statistic statistic, @NotNull EntityType entity, @NotNull String playerName) throws NullPointerException { return getFormattedStatistic(Target.PLAYER, statistic, null, entity, playerName); } @Override - public TextComponent getServerStat(@NotNull Statistic statistic) throws IllegalArgumentException { + public TextComponent getServerStat(@NotNull Statistic statistic) throws NullPointerException { return getFormattedStatistic(Target.SERVER, statistic, null, null, null); } @Override - public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException { + public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException { return getFormattedStatistic(Target.SERVER, statistic, material, null, null); } @Override - public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException { + public TextComponent getServerStat(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException { return getFormattedStatistic(Target.SERVER, statistic, null, entity, null); } @Override - public TextComponent getTopStats(@NotNull Statistic statistic) throws IllegalArgumentException { + public TextComponent getTopStats(@NotNull Statistic statistic) throws NullPointerException { return getFormattedStatistic(Target.TOP, statistic, null, null, null); } @Override - public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException { + public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull Material material) throws NullPointerException { return getFormattedStatistic(Target.TOP, statistic, material, null, null); } @Override - public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws IllegalArgumentException { + public TextComponent getTopStats(@NotNull Statistic statistic, @NotNull EntityType entity) throws NullPointerException { return getFormattedStatistic(Target.TOP, statistic, null, entity, null); } private TextComponent getFormattedStatistic(@NotNull Target selection, @NotNull Statistic statistic, - @Nullable Material material, @Nullable EntityType entity, @Nullable String playerName) throws IllegalArgumentException { + @Nullable Material material, @Nullable EntityType entity, @Nullable String playerName) throws NullPointerException { StatRequest request = requestManager.generateRequest(selection, statistic, material, entity, playerName); if (requestManager.validateAPIRequest(request)) { switch (selection) { @@ -94,6 +94,7 @@ public final class PlayerStatsAPI implements PlayerStats { } } } - throw new IllegalArgumentException("This is not a valid stat-request!"); + throw new NullPointerException("Not enough parameters are present for a valid statistic look-up! " + + "Make sure you include a block/item/entity if Statistic.Type is not Untyped, and include a playerName if you want a player-statistic"); } } \ No newline at end of file diff --git a/src/main/java/com/gmail/artemis/the/gr8/playerstats/msg/MessageBuilder.java b/src/main/java/com/gmail/artemis/the/gr8/playerstats/msg/MessageBuilder.java index d6274f2..2c9a1c5 100644 --- a/src/main/java/com/gmail/artemis/the/gr8/playerstats/msg/MessageBuilder.java +++ b/src/main/java/com/gmail/artemis/the/gr8/playerstats/msg/MessageBuilder.java @@ -352,7 +352,7 @@ public class MessageBuilder { /** Depending on the config settings, return either a TranslatableComponent representing the statName (and potential subStatName), or a TextComponent with capitalized English names.*/ private TextComponent getStatNameComponent(StatRequest request) { - if (config.useTranslatableComponents() && !request.isAPIRequest()) { + if (config.useTranslatableComponents()) { String statKey = languageKeyHandler.getStatKey(request.getStatistic()); String subStatKey = request.getSubStatEntry(); if (subStatKey != null) {