updated to further phase out PlaceholderHook, added contracts to expansion methods

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

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
+	 * The placeholder identifier of this expansion
-     *
+	 *
-     * @return {@link #getIdentifier()} by default, name of this expansion if specified
+	 * @return placeholder identifier that is associated with this expansion
-     */
+	 */
-    public String getName() {
+	@NotNull
-        return getIdentifier();
+	public abstract String getIdentifier();
-    }
 
-    /**
+	/**
-     * The placeholder identifier of this expansion
+	 * The author of this expansion
-     *
+	 *
-     * @return placeholder identifier that is associated with this expansion
+	 * @return name of the author for this expansion
-     */
+	 */
-    public abstract String getIdentifier();
+	@NotNull
+	public abstract String getAuthor();
 
-    /**
+	/**
-     * The author of this expansion
+	 * The version of this expansion
-     *
+	 *
-     * @return name of the author for this expansion
+	 * @return current version of this expansion
-     */
+	 */
-    public abstract String getAuthor();
+	@NotNull
+	public abstract String getVersion();
 
-    /**
+	@Nullable
-     * The version of this expansion
+	@Override /* override for now >:) */
-     *
+	public String onRequest(@Nullable final OfflinePlayer player, @NotNull final String params)
-     * @return current version of this expansion
+	{
-     */
+		return super.onRequest(player, params);
-    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<String> 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<String> 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);
-    }
 
 
-    /**
+	/**
-     * @deprecated As of versions greater than 2.8.7, use {@link #getRequiredPlugin()}
+	 * The name of this expansion
-     */
+	 *
-    @Deprecated
+	 * @return {@link #getIdentifier()} by default, name of this expansion if specified
-    public String getPlugin() {
+	 */
-        return null;
+	@NotNull
-    }
+	public String getName()
+	{
+		return getIdentifier();
+	}
 
-    /**
+	/**
-     * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description
+	 * The name of the plugin that this expansion hooks into. by default will null
-     */
+	 *
-    @Deprecated
+	 * @return plugin name that this expansion requires to function
-    public String getDescription() {
+	 */
-        return null;
+	@Nullable
-    }
+	public String getRequiredPlugin()
+	{
+		return null;
+	}
+
+	/**
+	 * The placeholders associated with this expansion
+	 *
+	 * @return placeholder list that this expansion provides
+	 */
+	@NotNull
+	public List<String> 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<String> 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;
-    }
 }

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)