Upstream
/
PlaceholderAPI
mirror of https://github.com/PlaceholderAPI/PlaceholderAPI.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

This commit is contained in:
Sxtanna 2020-07-26 18:46:00 -04:00
parent b63f10f749
commit a160f3abc9
3 changed files with 230 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
src/main/java/me/clip/placeholderapi/PlaceholderHook.java
View File

@ -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

376
src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java
View File

@ -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<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);
}
@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<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;
}
}

7
src/test/java/me/clip/placeholderapi/Values.java
View File

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