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 expansions; + + public ExpansionsLoadedEvent(List expansions) { + this.expansions = Collections.unmodifiableList(expansions); + } + /** + * Returns a unmodifiable list of {@link PlaceholderExpansion PlaceholderExpansions} that + * have been registered by PlaceholderAPI. + * + *

This list does not include manually registered PlaceholderExpansions. + * + * @return List of {@link PlaceholderExpansion registered PlaceholderExpansions}. + */ + @NotNull + public final List getExpansions(){ + return expansions; + } + @NotNull private static final HandlerList HANDLERS = new HandlerList(); diff --git a/src/main/java/me/clip/placeholderapi/expansion/Cacheable.java b/src/main/java/me/clip/placeholderapi/expansion/Cacheable.java index aa105f8..20b2fb8 100644 --- a/src/main/java/me/clip/placeholderapi/expansion/Cacheable.java +++ b/src/main/java/me/clip/placeholderapi/expansion/Cacheable.java @@ -21,9 +21,11 @@ package me.clip.placeholderapi.expansion; /** - * This interface allows a class which extends a {@link PlaceholderExpansion} to have the clear - * method called when the implementing expansion is unregistered from PlaceholderAPI. This is useful - * if we want to do things when the implementing hook is unregistered + * Classes implementing this interface will have a {@link #clear() clear void} that is called + * by PlaceholderAPI whenever the {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion} + * is unregistered. + * + *

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. + *

Example:

+ * returning a Map with key {@code foo} and value {@code bar} will result in the following config entry: + * + * 

+ * expansions:
+ *   myexpansion:
+ *     foo: "bar"
+ *
+ * + *

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. + *
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..a59893d 100644 --- a/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java +++ b/src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java @@ -259,7 +259,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 +320,35 @@ 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 registered = classes.stream() .filter(Objects::nonNull) .map(this::register) .filter(Optional::isPresent) + .map(Optional::get) + .collect(Collectors.toList()); + + final long needsUpdate = registered.stream() + .map(expansion -> plugin.getCloudExpansionManager().findCloudExpansionByName(expansion.getName()).orElse(null)) + .filter(Objects::nonNull) + .filter(CloudExpansion::shouldUpdate) .count(); - Msg.msg(sender, - registered == 0 ? "&6No expansions were registered!" - : registered + "&a placeholder hooks successfully registered!"); + StringBuilder message = new StringBuilder(registered.size() == 0 ? "&6" : "&a") + .append(registered.size()) + .append(' ') + .append("placeholder hook(s) registered!"); + + if (needsUpdate > 0) { + message.append("&6") + .append(needsUpdate) + .append(" placeholder hook(s) have an update available."); + } + + + Msg.msg(sender, message.toString()); - Bukkit.getPluginManager().callEvent(new ExpansionsLoadedEvent()); + Bukkit.getPluginManager().callEvent(new ExpansionsLoadedEvent(registered)); }); }