From a160f3abc95c39dfd29cb44c9ec82621f50c32ad Mon Sep 17 00:00:00 2001 From: Sxtanna Date: Sun, 26 Jul 2020 18:46:00 -0400 Subject: [PATCH] updated to further phase out PlaceholderHook, added contracts to expansion methods --- .../clip/placeholderapi/PlaceholderHook.java | 8 + .../expansion/PlaceholderExpansion.java | 376 ++++++++++-------- .../java/me/clip/placeholderapi/Values.java | 7 +- 3 files changed, 230 insertions(+), 161 deletions(-) diff --git a/src/main/java/me/clip/placeholderapi/PlaceholderHook.java b/src/main/java/me/clip/placeholderapi/PlaceholderHook.java index 629143c..4378c32 100644 --- a/src/main/java/me/clip/placeholderapi/PlaceholderHook.java +++ b/src/main/java/me/clip/placeholderapi/PlaceholderHook.java @@ -25,6 +25,10 @@ import org.bukkit.entity.Player; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +/** + * @deprecated This class will be completely removed in the next release, please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} + */ +@Deprecated public abstract class PlaceholderHook { @@ -35,8 +39,10 @@ public abstract class PlaceholderHook * player * @param params String passed to the hook to determine what value to return * @return value for the requested player and params + * @deprecated This method will be completely removed, please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#onRequest(OfflinePlayer, String)} */ @Nullable + @Deprecated public String onRequest(@Nullable final OfflinePlayer player, @NotNull final String params) { if (player != null && player.isOnline()) @@ -53,6 +59,8 @@ public abstract class PlaceholderHook * @param player {@link Player} to request the placeholder value for, null if not needed for a player * @param params String passed to the hook to determine what value to return * @return value for the requested player and params + * + * @deprecated This method will be completely removed, please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#onRequest(OfflinePlayer, String)} */ @Nullable @Deprecated diff --git a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java index 8cad404..d406331 100644 --- a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java +++ b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java @@ -23,177 +23,233 @@ package me.clip.placeholderapi.expansion; import me.clip.placeholderapi.PlaceholderAPI; import me.clip.placeholderapi.PlaceholderAPIPlugin; import me.clip.placeholderapi.PlaceholderHook; -import org.apache.commons.lang.Validate; import org.bukkit.Bukkit; +import org.bukkit.OfflinePlayer; import org.bukkit.configuration.ConfigurationSection; +import org.jetbrains.annotations.Contract; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; +import java.util.Collections; import java.util.List; -public abstract class PlaceholderExpansion extends PlaceholderHook { +public abstract class PlaceholderExpansion extends PlaceholderHook +{ - /** - * The name of this expansion - * - * @return {@link #getIdentifier()} by default, name of this expansion if specified - */ - public String getName() { - return getIdentifier(); - } + /** + * The placeholder identifier of this expansion + * + * @return placeholder identifier that is associated with this expansion + */ + @NotNull + public abstract String getIdentifier(); - /** - * The placeholder identifier of this expansion - * - * @return placeholder identifier that is associated with this expansion - */ - public abstract String getIdentifier(); + /** + * The author of this expansion + * + * @return name of the author for this expansion + */ + @NotNull + public abstract String getAuthor(); - /** - * The author of this expansion - * - * @return name of the author for this expansion - */ - public abstract String getAuthor(); + /** + * The version of this expansion + * + * @return current version of this expansion + */ + @NotNull + public abstract String getVersion(); - /** - * The version of this expansion - * - * @return current version of this expansion - */ - public abstract String getVersion(); - - /** - * The name of the plugin that this expansion hooks into. by default will return the deprecated - * {@link #getPlugin()} method - * - * @return plugin name that this expansion requires to function - */ - public String getRequiredPlugin() { - return getPlugin(); - } - - /** - * The placeholders associated with this expansion - * - * @return placeholder list that this expansion provides - */ - public List getPlaceholders() { - return null; - } - - /** - * Expansions that do not use the ecloud and instead register from the dependency should set this - * to true to ensure that your placeholder expansion is not unregistered when the papi reload - * command is used - * - * @return if this expansion should persist through placeholder reloads - */ - public boolean persist() { - return false; - } - - /** - * Check if this placeholder identifier has already been registered - * - * @return true if the identifier for this expansion is already registered - */ - public boolean isRegistered() { - Validate.notNull(getIdentifier(), "Placeholder identifier can not be null!"); - return PlaceholderAPI.isRegistered(getIdentifier()); - } - - /** - * If any requirements need to be checked before this expansion should register, you can check - * them here - * - * @return true if this hook meets all the requirements to register - */ - public boolean canRegister() { - return getRequiredPlugin() == null || Bukkit.getPluginManager().getPlugin(getRequiredPlugin()) != null; - } - - /** - * Attempt to register this PlaceholderExpansion - * - * @return true if this expansion is now registered with PlaceholderAPI - */ - public boolean register() { - Validate.notNull(getIdentifier(), "Placeholder identifier can not be null!"); - return canRegister() && getPlaceholderAPI().getLocalExpansionManager().register(this); - } - - /** - * Quick getter for the {@link PlaceholderAPIPlugin} instance - * - * @return {@link PlaceholderAPIPlugin} instance - */ - public PlaceholderAPIPlugin getPlaceholderAPI() { - return PlaceholderAPIPlugin.getInstance(); - } - - public String getString(String path, String def) { - return getPlaceholderAPI().getConfig() - .getString("expansions." + getIdentifier() + "." + path, def); - } - - public int getInt(String path, int def) { - return getPlaceholderAPI().getConfig() - .getInt("expansions." + getIdentifier() + "." + path, def); - } - - public long getLong(String path, long def) { - return getPlaceholderAPI().getConfig() - .getLong("expansions." + getIdentifier() + "." + path, def); - } - - public double getDouble(String path, double def) { - return getPlaceholderAPI().getConfig() - .getDouble("expansions." + getIdentifier() + "." + path, def); - } - - public List getStringList(String path) { - return getPlaceholderAPI().getConfig() - .getStringList("expansions." + getIdentifier() + "." + path); - } - - public Object get(String path, Object def) { - return getPlaceholderAPI().getConfig().get("expansions." + getIdentifier() + "." + path, def); - } - - public ConfigurationSection getConfigSection(String path) { - return getPlaceholderAPI().getConfig() - .getConfigurationSection("expansions." + getIdentifier() + "." + path); - } - - public ConfigurationSection getConfigSection() { - return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier()); - } - - public boolean configurationContains(String path) { - return getPlaceholderAPI().getConfig().contains("expansions." + getIdentifier() + "." + path); - } + @Nullable + @Override /* override for now >:) */ + public String onRequest(@Nullable final OfflinePlayer player, @NotNull final String params) + { + return super.onRequest(player, params); + } - /** - * @deprecated As of versions greater than 2.8.7, use {@link #getRequiredPlugin()} - */ - @Deprecated - public String getPlugin() { - return null; - } + /** + * The name of this expansion + * + * @return {@link #getIdentifier()} by default, name of this expansion if specified + */ + @NotNull + public String getName() + { + return getIdentifier(); + } - /** - * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description - */ - @Deprecated - public String getDescription() { - return null; - } + /** + * The name of the plugin that this expansion hooks into. by default will null + * + * @return plugin name that this expansion requires to function + */ + @Nullable + public String getRequiredPlugin() + { + return null; + } + + /** + * The placeholders associated with this expansion + * + * @return placeholder list that this expansion provides + */ + @NotNull + public List getPlaceholders() + { + return Collections.emptyList(); + } + + + /** + * Expansions that do not use the ecloud and instead register from the dependency should set this + * to true to ensure that your placeholder expansion is not unregistered when the papi reload + * command is used + * + * @return if this expansion should persist through placeholder reloads + */ + public boolean persist() + { + return false; + } + + + /** + * Check if this placeholder identifier has already been registered + * + * @return true if the identifier for this expansion is already registered + */ + public final boolean isRegistered() + { + return PlaceholderAPI.isRegistered(getIdentifier()); + } + + + /** + * If any requirements need to be checked before this expansion should register, you can check + * them here + * + * @return true if this hook meets all the requirements to register + */ + public boolean canRegister() + { + return getRequiredPlugin() == null || Bukkit.getPluginManager().getPlugin(getRequiredPlugin()) != null; + } + + /** + * Attempt to register this PlaceholderExpansion + * + * @return true if this expansion is now registered with PlaceholderAPI + */ + public boolean register() + { + return canRegister() && getPlaceholderAPI().getLocalExpansionManager().register(this); + } + + + /** + * Quick getter for the {@link PlaceholderAPIPlugin} instance + * + * @return {@link PlaceholderAPIPlugin} instance + */ + @NotNull + public final PlaceholderAPIPlugin getPlaceholderAPI() + { + return PlaceholderAPIPlugin.getInstance(); + } + + + // === Configuration === + + @Nullable + public final ConfigurationSection getConfigSection() + { + return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier()); + } + + @Nullable + public final ConfigurationSection getConfigSection(@NotNull final String path) + { + final ConfigurationSection section = getConfigSection(); + return section == null ? null : section.getConfigurationSection(path); + } + + @Nullable + @Contract("_, !null -> !null") + public final Object get(@NotNull final String path, final Object def) + { + final ConfigurationSection section = getConfigSection(); + return section == null ? def : section.get(path, def); + } + + public final int getInt(@NotNull final String path, final int def) + { + final ConfigurationSection section = getConfigSection(); + return section == null ? def : section.getInt(path, def); + } + + public final long getLong(@NotNull final String path, final long def) + { + final ConfigurationSection section = getConfigSection(); + return section == null ? def : section.getLong(path, def); + } + + public final double getDouble(@NotNull final String path, final double def) + { + final ConfigurationSection section = getConfigSection(); + return section == null ? def : section.getDouble(path, def); + } + + @Nullable + @Contract("_, !null -> !null") + public final String getString(@NotNull final String path, @Nullable final String def) + { + final ConfigurationSection section = getConfigSection(); + return section == null ? def : section.getString(path, def); + } + + @NotNull + public final List getStringList(@NotNull final String path) + { + final ConfigurationSection section = getConfigSection(); + return section == null ? Collections.emptyList() : section.getStringList(path); + } + + public final boolean configurationContains(@NotNull final String path) + { + final ConfigurationSection section = getConfigSection(); + return section != null && section.contains(path); + } + + + // === Deprecated API === + + /** + * @deprecated As of versions greater than 2.8.7, use {@link #getRequiredPlugin()} + */ + @Deprecated + public final String getPlugin() + { + return null; + } + + /** + * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description + */ + @Deprecated + public final String getDescription() + { + return null; + } + + /** + * @deprecated As of versions greater than 2.8.7, use the expansion cloud to display a link + */ + @Deprecated + public final String getLink() + { + return null; + } - /** - * @deprecated As of versions greater than 2.8.7, use the expansion cloud to display a link - */ - @Deprecated - public String getLink() { - return null; - } } diff --git a/src/test/java/me/clip/placeholderapi/Values.java b/src/test/java/me/clip/placeholderapi/Values.java index 89e3cad..bf8b0ca 100644 --- a/src/test/java/me/clip/placeholderapi/Values.java +++ b/src/test/java/me/clip/placeholderapi/Values.java @@ -6,6 +6,8 @@ import me.clip.placeholderapi.replacer.CharsReplacer; import me.clip.placeholderapi.replacer.RegexReplacer; import me.clip.placeholderapi.replacer.Replacer; import org.bukkit.OfflinePlayer; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; public interface Values { @@ -31,18 +33,21 @@ public interface Values public static final String PLAYER_NAME = "Sxtanna"; + @NotNull @Override public String getIdentifier() { return "player"; } + @NotNull @Override public String getAuthor() { return "Sxtanna"; } + @NotNull @Override public String getVersion() { @@ -50,7 +55,7 @@ public interface Values } @Override - public String onRequest(final OfflinePlayer player, final String params) + public String onRequest(@Nullable final OfflinePlayer player, @NotNull final String params) { final String[] parts = params.split("_"); if (parts.length == 0)