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/PlaceholderExpansion.java b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java
index 1e71a45..a7ff90b 100644
--- a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java
+++ b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java
@@ -22,6 +22,7 @@ package me.clip.placeholderapi.expansion;
import java.util.Collections;
import java.util.List;
+import java.util.logging.Level;
import me.clip.placeholderapi.PlaceholderAPIPlugin;
import me.clip.placeholderapi.PlaceholderHook;
import org.bukkit.Bukkit;
@@ -275,7 +276,6 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
* @param def The default boolean to return when the ConfigurationSection is null
* @return boolean from the provided path or the default one provided
*/
- @NotNull
public final boolean getBoolean(@NotNull final String path, final boolean def) {
final ConfigurationSection section = getConfigSection();
return section == null ? def : section.getBoolean(path, def);
@@ -293,6 +293,71 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
final ConfigurationSection section = getConfigSection();
return section != null && section.contains(path);
}
+
+ /**
+ * Logs the provided message with the provided Level in the console.
+ * 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"
+ *
The message will be prefixed with {@link #getName() [<expansion name>]
}
+ *
+ * @param level The Level at which the message should be logged with
+ * @param msg The message to log
+ */
+ public void log(Level level, String msg) {
+ getPlaceholderAPI().getLogger().log(level, "[" + getName() + "] " + msg);
+ }
+
+ /**
+ * Logs the provided message and Throwable with the provided Level in the console.
+ *
The message will be prefixed with {@link #getName() [<expansion name>]
}
+ *
+ * @param level The Level at which the message should be logged with
+ * @param msg The message to log
+ * @param throwable The Throwable to log
+ */
+ public void log(Level level, String msg, Throwable throwable) {
+ getPlaceholderAPI().getLogger().log(level, "[" + getName() + "] " + msg, throwable);
+ }
+
+ /**
+ * Logs the provided message with Level "info".
+ *
The message will be prefixed with {@link #getName() [<expansion name>]
}
+ *
+ * @param msg The message to log
+ */
+ public void info(String msg) {
+ log(Level.INFO, msg);
+ }
+
+ /**
+ * Logs the provided message with Level "warning".
+ *
The message will be prefixed with {@link #getName() [<expansion name>]
}
+ *
+ * @param msg The message to log
+ */
+ public void warning(String msg) {
+ log(Level.WARNING, msg);
+ }
+
+ /**
+ * Logs the provided message with Level "severe" (error).
+ *
The message will be prefixed with {@link #getName() [<expansion name>]
}
+ *
+ * @param msg The message to log
+ */
+ public void severe(String msg) {
+ log(Level.SEVERE, msg);
+ }
+
+ /**
+ * Logs the provided message and Throwable with Level "severe" (error).
+ *
The message will be prefixed with {@link #getName() [<expansion name>]
}
+ *
+ * @param msg The message to log
+ * @param throwable The Throwable to log
+ */
+ public void severe(String msg, Throwable throwable) {
+ log(Level.SEVERE, msg, throwable);
+ }
+
/**
* Whether the provided Object is an instance of this PlaceholderExpansion.
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.
+ *
+ *
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