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) {