diff --git a/build.gradle b/build.gradle index 172866c..c4b4487 100644 --- a/build.gradle +++ b/build.gradle @@ -24,7 +24,6 @@ repositories { dependencies { implementation "org.bstats:bstats-bukkit:2.2.1" - implementation "net.kyori:adventure-platform-bukkit:4.0.0" compileOnly "org.spigotmc:spigot-api:1.17.1-R0.1-SNAPSHOT" diff --git a/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java b/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java index 6f812dc..e54e3e9 100644 --- a/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java +++ b/src/main/java/me/clip/placeholderapi/events/ExpansionRegisterEvent.java @@ -27,8 +27,11 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * Indicates that a {@link PlaceholderExpansion} has been registered by - * PlaceholderAPI. + * This event indicates that a single {@link PlaceholderExpansion PlaceholderExpansion} has + * been registered in PlaceholderAPI. + * + *
To know when all Expansions have been registered, use the
+ * {@link me.clip.placeholderapi.events.ExpansionsLoadedEvent ExpansionsLoadedEvent} instead.
*/
public final class ExpansionRegisterEvent extends Event implements Cancellable {
@@ -48,15 +51,25 @@ public final class ExpansionRegisterEvent extends Event implements Cancellable {
}
/**
- * The {@link PlaceholderExpansion expansion} that was registered.
+ * The {@link PlaceholderExpansion PlaceholderExpansion} that was registered in PlaceholderAPI.
+ *
The PlaceholderExpansion will be available for use when the event
+ * {@link #isCancelled() was not cancelled}!
*
- * @return The {@link PlaceholderExpansion} instance.
+ * @return Current instance of the registered {@link PlaceholderExpansion PlaceholderExpansion}
*/
@NotNull
public PlaceholderExpansion getExpansion() {
return expansion;
}
+ /**
+ * Indicates if this event was cancelled or not.
+ *
A cancelled Event will result in the {@link #getExpansion() PlaceholderExpansion} NOT
+ * being added to PlaceholderAPI's internal list and will therefore be considered not registered
+ * anymore.
+ *
+ * @return Whether the event has been cancelled or not.
+ */
@Override
public boolean isCancelled() {
return cancelled;
diff --git a/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java b/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java
index 4c0beb1..6156003 100644
--- a/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java
+++ b/src/main/java/me/clip/placeholderapi/events/ExpansionUnregisterEvent.java
@@ -26,15 +26,19 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
- * Indicates that a {@link PlaceholderExpansion} had been unregistered by
- * PlaceholderAPI.
+ * This event indicates that a {@link PlaceholderExpansion PlaceholderExpansion} has been
+ * unregistered by PlaceholderAPI.
+ *
+ *
Note that this event is triggered before the PlaceholderExpansion is completely
+ * removed.
+ *
This includes removing any Listeners, stopping active tasks and clearing the cache of
+ * the PlaceholderExpansion.
*/
public final class ExpansionUnregisterEvent extends Event {
@NotNull
private static final HandlerList HANDLERS = new HandlerList();
-
-
+
@NotNull
private final PlaceholderExpansion expansion;
@@ -48,9 +52,9 @@ public final class ExpansionUnregisterEvent extends Event {
}
/**
- * The {@link PlaceholderExpansion expansion} that was unregistered.
+ * The {@link PlaceholderExpansion PlaceholderExpansion} that was unregistered.
*
- * @return The {@link PlaceholderExpansion} instance.
+ * @return The {@link PlaceholderExpansion PlaceholderExpansion} instance.
*/
@NotNull
public PlaceholderExpansion getExpansion() {
diff --git a/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java b/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java
index b173007..f9ca024 100644
--- a/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java
+++ b/src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java
@@ -21,18 +21,42 @@
package me.clip.placeholderapi.events;
+import java.util.Collections;
+import java.util.List;
+import me.clip.placeholderapi.expansion.PlaceholderExpansion;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
- * Indicates that all {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlayceholderExpansions}
- * have been loaded.
- *
This event is fired on Server load and when reloading the
- * confiuration.
+ * This event indicated that all {@link PlaceholderExpansion PlaceholderExpansions} have
+ * been registered in PlaceholderAPI and can now be used.
+ *
This even will also be triggered whenever PlaceholderAPI gets reloaded.
+ *
+ *
All PlaceholderExpansions, except for those loaded by plugins, are loaded
+ * after Spigot triggered its ServerLoadEvent (1.13+), or after PlaceholderAPI has been enabled.
*/
public class ExpansionsLoadedEvent extends Event {
+
+ private final List This list does not include manually registered PlaceholderExpansions.
+ *
+ * @return List of {@link PlaceholderExpansion registered PlaceholderExpansions}.
+ */
+ @NotNull
+ public final List This allows you to execute things such as clearing internal caches, saving data to files, etc.
*
* @author Ryan McCarthy
*/
diff --git a/src/main/java/me/clip/placeholderapi/expansion/Cleanable.java b/src/main/java/me/clip/placeholderapi/expansion/Cleanable.java
index b408acf..9b369eb 100644
--- a/src/main/java/me/clip/placeholderapi/expansion/Cleanable.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/Cleanable.java
@@ -23,9 +23,11 @@ package me.clip.placeholderapi.expansion;
import org.bukkit.entity.Player;
/**
- * This interface allows a class which extends a {@link PlaceholderExpansion} to have the cleanup
- * method called every time a player leaves the server. This is useful if we want to clean up after
- * the player
+ * Classes implementing this interface will have a {@link #cleanup(Player) cleanup void} that is
+ * called by PlaceholderAPI whenever a Player leaves the server.
+ *
+ * This can be useful for cases where you keep data of the player in a cache or similar
+ * and want to free up space whenever they leave.
*
* @author Ryan McCarthy
*/
diff --git a/src/main/java/me/clip/placeholderapi/expansion/Configurable.java b/src/main/java/me/clip/placeholderapi/expansion/Configurable.java
index a20b73b..1e07fb4 100644
--- a/src/main/java/me/clip/placeholderapi/expansion/Configurable.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/Configurable.java
@@ -23,18 +23,32 @@ package me.clip.placeholderapi.expansion;
import java.util.Map;
/**
- * Any {@link PlaceholderExpansion} class which implements configurable will have any options listed
- * in the {@link #getDefaults()} map automatically added to the PlaceholderAPI config.yml file
+ * Implementing this interface allows {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansions}
+ * to set a list of default configuration values through the {@link #getDefaults() getDefaults method}
+ * that should be added to the config.yml of PlaceholderAPI.
+ *
+ * The entries will be added under {@code expansions} as their own section.
+ * The configuration is set before the PlaceholderExpansion is registered!
*
* @author Ryan McCarthy
*/
public interface Configurable {
/**
- * This method will be called before the implementing class is registered to obtain a map of
- * configuration options that the implementing class needs These paths and values will be added to
- * the PlaceholderAPI config.yml in the configuration section expansions.(placeholder
- * identifier).(your key): (your value)
+ * The map returned by this method will be used to set config options in PlaceholderAPI's config.yml.
+ *
+ * The key and value pairs are set under a section named after your
+ * {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion} in the
+ * {@code expansions} section of the config.
*
* @return Map of config path / values which need to be added / removed from the PlaceholderAPI
* config.yml file
diff --git a/src/main/java/me/clip/placeholderapi/expansion/Relational.java b/src/main/java/me/clip/placeholderapi/expansion/Relational.java
index 6d05e94..ba1872c 100644
--- a/src/main/java/me/clip/placeholderapi/expansion/Relational.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/Relational.java
@@ -22,7 +22,22 @@ package me.clip.placeholderapi.expansion;
import org.bukkit.entity.Player;
+/**
+ * Implementing this interface allows your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
+ * to be used as a relational placeholder expansion.
+ *
+ * Relational placeholders take two Players as input and are always prefixed with {@code rel_},
+ * so {@code %foo_bar%} becomes {@code %rel_foo_bar%}
+ */
public interface Relational {
+ /**
+ * This method is called whenever a placeholder starting with {@code rel_} is called.
+ *
+ * @param one The first player used for the placeholder.
+ * @param two The second player used for the placeholder.
+ * @param identifier The text right after the expansion's name (%expansion_identifier%)
+ * @return Parsed String from the expansion.
+ */
String onPlaceholderRequest(Player one, Player two, String identifier);
}
diff --git a/src/main/java/me/clip/placeholderapi/expansion/Taskable.java b/src/main/java/me/clip/placeholderapi/expansion/Taskable.java
index fa0ac21..f71aef8 100644
--- a/src/main/java/me/clip/placeholderapi/expansion/Taskable.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/Taskable.java
@@ -20,18 +20,24 @@
package me.clip.placeholderapi.expansion;
-
+/**
+ * Implementing this interface adds the {@link #start() start} and {@link #stop() stop} void
+ * methods to your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}.
+ *
+ * This can be used to execute methods and tasks whenever the PlaceholderExpansion has been
+ * successfully (un)registered.
+ */
public interface Taskable {
/**
- * Called when the implementing class has successfully been registered to the placeholder map
- * Tasks that need to be performed when this expansion is registered should go here
+ * Called when the implementing class has successfully been registered to the placeholder map.
+ * Example:
+ * returning a Map with key {@code foo} and value {@code bar} will result in the following config entry:
+ *
+ *
+ *
+ *
+ * expansions:
+ * myexpansion:
+ * foo: "bar"
+ *
Tasks that need to be performed when this expansion is registered should go here
*/
void start();
/**
- * Called when the implementing class has been unregistered from PlaceholderAPI Tasks that need to
- * be performed when this expansion has unregistered should go here
+ * Called when the implementing class has been unregistered from PlaceholderAPI.
+ *
Tasks that need to be performed when this expansion has unregistered should go here
*/
void stop();
}
diff --git a/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java b/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java
index 872215c..abded95 100644
--- a/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java
@@ -160,7 +160,11 @@ public final class LocalExpansionManager implements Listener {
@NotNull final Class extends PlaceholderExpansion> clazz) {
try {
final PlaceholderExpansion expansion = createExpansionInstance(clazz);
-
+
+ if(expansion == null){
+ return Optional.empty();
+ }
+
Objects.requireNonNull(expansion.getAuthor(), "The expansion author is null!");
Objects.requireNonNull(expansion.getIdentifier(), "The expansion identifier is null!");
Objects.requireNonNull(expansion.getVersion(), "The expansion version is null!");
@@ -259,7 +263,8 @@ public final class LocalExpansionManager implements Listener {
Bukkit.getPluginManager().registerEvents(((Listener) expansion), plugin);
}
- plugin.getLogger().info("Successfully registered expansion: " + expansion.getIdentifier());
+ plugin.getLogger().info("Successfully registered expansion: " + expansion.getIdentifier() +
+ " [" + expansion.getVersion() + "]");
if (expansion instanceof Taskable) {
((Taskable) expansion).start();
@@ -319,18 +324,37 @@ public final class LocalExpansionManager implements Listener {
plugin.getLogger().log(Level.SEVERE, "failed to load class files of expansions", exception);
return;
}
-
- final long registered = classes.stream()
+
+ final List