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,28 +23,25 @@ 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 {
-
-    /**
-     * The name of this expansion
-     *
-     * @return {@link #getIdentifier()} by default, name of this expansion if specified
-     */
-    public String getName() {
-        return getIdentifier();
-    }
+public abstract class PlaceholderExpansion extends PlaceholderHook
+{
 
 	/**
 	 * The placeholder identifier of this expansion
 	 *
 	 * @return placeholder identifier that is associated with this expansion
 	 */
+	@NotNull
 	public abstract String getIdentifier();
 
 	/**
@@ -52,6 +49,7 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 	 *
 	 * @return name of the author for this expansion
 	 */
+	@NotNull
 	public abstract String getAuthor();
 
 	/**
@@ -59,16 +57,37 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 	 *
 	 * @return current version of this expansion
 	 */
+	@NotNull
 	public abstract String getVersion();
 
+	@Nullable
+	@Override /* override for now >:) */
+	public String onRequest(@Nullable final OfflinePlayer player, @NotNull final String params)
+	{
+		return super.onRequest(player, params);
+	}
+
+
 	/**
-     * The name of the plugin that this expansion hooks into. by default will return the deprecated
-     * {@link #getPlugin()} method
+	 * The name of this expansion
+	 *
+	 * @return {@link #getIdentifier()} by default, name of this expansion if specified
+	 */
+	@NotNull
+	public String getName()
+	{
+		return getIdentifier();
+	}
+
+	/**
+	 * The name of the plugin that this expansion hooks into. by default will null
 	 *
 	 * @return plugin name that this expansion requires to function
 	 */
-    public String getRequiredPlugin() {
-        return getPlugin();
+	@Nullable
+	public String getRequiredPlugin()
+	{
+		return null;
 	}
 
 	/**
@@ -76,10 +95,13 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 	 *
 	 * @return placeholder list that this expansion provides
 	 */
-    public List<String> getPlaceholders() {
-        return null;
+	@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
@@ -87,27 +109,31 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 	 *
 	 * @return if this expansion should persist through placeholder reloads
 	 */
-    public boolean persist() {
+	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!");
+	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() {
+	public boolean canRegister()
+	{
 		return getRequiredPlugin() == null || Bukkit.getPluginManager().getPlugin(getRequiredPlugin()) != null;
 	}
 
@@ -116,68 +142,95 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 	 *
 	 * @return true if this expansion is now registered with PlaceholderAPI
 	 */
-    public boolean register() {
-        Validate.notNull(getIdentifier(), "Placeholder identifier can not be null!");
+	public boolean register()
+	{
 		return canRegister() && getPlaceholderAPI().getLocalExpansionManager().register(this);
 	}
 
+
 	/**
 	 * Quick getter for the {@link PlaceholderAPIPlugin} instance
 	 *
 	 * @return {@link PlaceholderAPIPlugin} instance
 	 */
-    public PlaceholderAPIPlugin getPlaceholderAPI() {
+	@NotNull
+	public final 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);
-    }
+	// === Configuration ===
 
-    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() {
+	@Nullable
+	public final ConfigurationSection getConfigSection()
+	{
 		return getPlaceholderAPI().getConfig().getConfigurationSection("expansions." + getIdentifier());
 	}
 
-    public boolean configurationContains(String path) {
-        return getPlaceholderAPI().getConfig().contains("expansions." + getIdentifier() + "." + path);
+	@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 String getPlugin() {
+	public final String getPlugin()
+	{
 		return null;
 	}
 
@@ -185,7 +238,8 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 	 * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description
 	 */
 	@Deprecated
-    public String getDescription() {
+	public final String getDescription()
+	{
 		return null;
 	}
 
@@ -193,7 +247,9 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 	 * @deprecated As of versions greater than 2.8.7, use the expansion cloud to display a link
 	 */
 	@Deprecated
-    public String getLink() {
+	public final 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)