Merge 46f91f5f11 into f3cb7635c2

src/main/java/me/clip/placeholderapi/PlaceholderHook.java

@@ -25,8 +25,22 @@ import org.bukkit.entity.Player;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+@Deprecated
 public abstract class PlaceholderHook {
+
+  /**
+   * Please see {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(OfflinePlayer, String) PlaceholderExpansion#parsePlaceholder(OfflinePlayer, String)}
+   * for a full description of what this method is used for.
+   * 
+   * @param player Possibly-null OfflinePlayer instance to use.
+   * @param params String after {@code %<expansion>_} and before the second percent symbol.
+   * @return Possibly-null String depending on the Expansions returned value.
+   * @deprecated Planned for removal in 2.14.0
+   *             <br>Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(OfflinePlayer, String) parsePlaceholders(OfflinePlayer, String)}
+   *             instead
+   */
   @Nullable
+  @Deprecated
   public String onRequest(final OfflinePlayer player, @NotNull final String params) {
     if (player != null && player.isOnline()) {
       return onPlaceholderRequest((Player) player, params);
@@ -35,7 +49,20 @@ public abstract class PlaceholderHook {
     return onPlaceholderRequest(null, params);
   }
 
+  /**
+   * Please see {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(Player, String) PlaceholderExpansion#parsePlaceholder(Player, String)}
+   * for a full description of what this method is used for.
+   *
+   * @param player Possibly-null Player instance to use.
+   * @param params String after {@code %<expansion>_} and before the second percent symbol.
+   * @return Possibly-null String depending on the Expansions returned value.
+   * 
+   * @deprecated Planned for removal in 2.14.0
+   *             <br>Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(Player, String) parsePlaceholders(Player, String)}
+   *             instead
+   */
   @Nullable
+  @Deprecated
   public String onPlaceholderRequest(final Player player, @NotNull final String params) {
     return null;
   }

src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java

@@ -26,7 +26,9 @@ import java.util.logging.Level;
 import me.clip.placeholderapi.PlaceholderAPIPlugin;
 import me.clip.placeholderapi.PlaceholderHook;
 import org.bukkit.Bukkit;
+import org.bukkit.OfflinePlayer;
 import org.bukkit.configuration.ConfigurationSection;
+import org.bukkit.entity.Player;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
@@ -398,6 +400,62 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
         getAuthor(), getVersion());
   }
 
+  /**
+   * This method is called first whenever PlaceholderAPI finds a valid placeholder with a matching expansion.
+   * <br>When called, the provided OfflinePlayer instance can be one of 3 possible states:
+   * 
+   * <ul>
+   *   <li>Not null and online</li>
+   *   <li>Not null and offline</li>
+   *   <li>Null</li>
+   * </ul>
+   * 
+   * When not overridden by the called expansion will the method as of now call
+   * {@link PlaceholderHook#onRequest(OfflinePlayer, String) PlaceholderHook#onRequest(OfflinePlayer, String)}.
+   * <br>This behaviour will change in a future version to call {@link #parsePlaceholders(Player, String) parsePlaceholders(Player, String)}
+   * with the OfflinePlayer either being casted to a Player (When online), or {@link null}.
+   * 
+   * <p>To use this method in your PlaceholderExpansion, override it and return either a String or {@code null}.
+   * <br>When {@code null} is returned will PlaceholderAPI see it as an "invalid placeholder" and return
+   * the content as-is in the final String.
+   * 
+   * @param player The OfflinePlayer to use.
+   * @param params The parameters of the placeholder, right after the first underscore.
+   * @return Parsed placeholder, or null depending on the Expansion's handling of it.
+   */
+  @Nullable
+  public String parsePlaceholders(@Nullable OfflinePlayer player, @NotNull String params) {
+    return this.onRequest(player, params);
+  }
+
+  /**
+   * This method is called whenever PlaceholderAPI finds a valid placeholder with a matching expansion
+   * AND {@link #parsePlaceholders(OfflinePlayer, String) parsePlaceholder(OfflinePlayer, String)} isn't
+   * overridden by the expansion in question.
+   * <br>When called, the provided Player instance can be one of 2 possible states:
+   * 
+   * <ul>
+   *   <li>Not null and online</li>
+   *   <li>Null</li>
+   * </ul>
+   *
+   * When not overridden by the called expansion will the method as of now call
+   * {@link PlaceholderHook#onPlaceholderRequest(Player, String) PlaceholderHook#onPlaceholderRequest(Player, String)}.
+   * <br>This behaviour will change in a future version to instead return {@code null}.
+   * 
+   * <p>To use this method in your PlaceholderExpansion, override it and return either a String or {@code null}.
+   * <br>When {@code null} is returned will PlaceholderAPI see it as an "invalid placeholder" and return
+   * the content as-is in the final String.
+   * 
+   * @param player The Player to use. May be null
+   * @param params The parameters of the placeholder, right after the first underscore.
+   * @return Parsed placeholder, or null depending on the Expansion's handling of it.
+   */
+  @Nullable
+  public String parsePlaceholders(@Nullable Player player, @NotNull String params){
+    return this.onPlaceholderRequest(player, params);
+  }
+  
   // === Deprecated API ===
 
   /**

src/main/java/me/clip/placeholderapi/expansion/Relational.java

@@ -21,23 +21,29 @@
 package me.clip.placeholderapi.expansion;
 
 import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
- * Implementing this interface allows your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
- * to be used as a relational placeholder expansion.
+ * This interface should be used when your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion}
+ * should support relational placeholders.
  * 
- * <p>Relational placeholders take two Players as input and are always prefixed with {@code rel_},
- * so {@code %foo_bar%} becomes {@code %rel_foo_bar%}
+ * <p>The difference between relational placeholders and normal ones is, that relational ones start
+ * with a {@code rel_} prefix and have two Players provided, instead of one.
+ * <br>The main purpose is to return a String based on the "relationship" between the two players
+ * (i.e. if both are within the same world).
  */
 public interface Relational {
 
   /**
-   * This method is called whenever a placeholder starting with {@code rel_} is called.
+   * This method will be called whenever a valid placeholder in the format {@code %rel_<expansion>_<identifier>%}
+   * is found.
    * 
-   * @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_<b>identifier</b>%)
-   * @return Parsed String from the expansion.
+   * @param one The first player to use for comparison.
+   * @param two The second player to use for comparison
+   * @param identifier String right after {@code %rel_<expansion>_} and before the second percent symbol.
+   * @return Possibly-null String, depending on what the expansion returns.
    */
-  String onPlaceholderRequest(Player one, Player two, String identifier);
+  @Nullable
+  String onPlaceholderRequest(Player one, Player two, @NotNull String identifier);
 }

src/main/java/me/clip/placeholderapi/replacer/CharsReplacer.java

@@ -116,7 +116,7 @@ public final class CharsReplacer implements Replacer {
         continue;
       }
 
-      final String replacement = placeholder.onRequest(player, parametersString);
+      final String replacement = placeholder.parsePlaceholders(player, parametersString);
       if (replacement == null) {
         builder.append(closure.head).append(identifierString);
 

src/main/java/me/clip/placeholderapi/replacer/RegexReplacer.java

@@ -61,7 +61,7 @@ public final class RegexReplacer implements Replacer {
         continue;
       }
 
-      final String requested = expansion.onRequest(player, parameters);
+      final String requested = expansion.parsePlaceholders(player, parameters);
       matcher.appendReplacement(builder, requested != null ? requested : matcher.group(0));
     }
     while (matcher.find());