SPIGOT-2272: Add API for virtual Merchants

By: Lukas Hennig <lukas@wirsindwir.de>

paper-api/src/main/java/org/bukkit/inventory/Merchant.java

@@ -0,0 +1,69 @@
+package org.bukkit.inventory;
+
+import java.util.List;
+
+import org.bukkit.entity.HumanEntity;
+
+/**
+ * Represents a merchant. A merchant is a special type of inventory which can
+ * facilitate custom trades between items.
+ */
+public interface Merchant {
+
+    /**
+     * Get a list of trades currently available from this merchant.
+     *
+     * @return an immutable list of trades
+     */
+    List<MerchantRecipe> getRecipes();
+
+    /**
+     * Set the list of trades currently available from this merchant.
+     * <br>
+     * This will not change the selected trades of players currently trading
+     * with this merchant.
+     *
+     * @param recipes a list of recipes
+     */
+    void setRecipes(List<MerchantRecipe> recipes);
+
+    /**
+     * Get the recipe at a certain index of this merchant's trade list.
+     *
+     * @param i the index
+     * @return the recipe
+     * @throws IndexOutOfBoundsException
+     */
+    MerchantRecipe getRecipe(int i) throws IndexOutOfBoundsException;
+
+    /**
+     * Set the recipe at a certain index of this merchant's trade list.
+     *
+     * @param i the index
+     * @param recipe the recipe
+     * @throws IndexOutOfBoundsException
+     */
+    void setRecipe(int i, MerchantRecipe recipe) throws IndexOutOfBoundsException;
+
+    /**
+     * Get the number of trades this merchant currently has available.
+     *
+     * @return the recipe count
+     */
+    int getRecipeCount();
+
+    /**
+     * Gets whether this merchant is currently trading.
+     *
+     * @return whether the merchant is trading
+     */
+    boolean isTrading();
+
+    /**
+     * Gets the player this merchant is trading with, or null if it is not
+     * currently trading.
+     *
+     * @return the trader, or null
+     */
+    HumanEntity getTrader();
+}

paper-api/src/main/java/org/bukkit/inventory/MerchantInventory.java

@@ -1,9 +1,10 @@
 package org.bukkit.inventory;
 
 /**
- * Represents a trading inventory between a player and a villager.
+ * Represents a trading inventory between a player and a merchant.
  * <br>
- * The holder of this Inventory is the owning Villager.
+ * The holder of this Inventory is the owning Villager, or null if the player is
+ * trading with a merchant created by a plugin.
  */
 public interface MerchantInventory extends Inventory {
 

paper-api/src/main/java/org/bukkit/inventory/MerchantRecipe.java

@@ -5,7 +5,7 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Represents a Villager's trade.
+ * Represents a merchant's trade.
  *
  * Trades can take one or two ingredients, and provide one result. The
  * ingredients' Itemstack amounts are respected in the trade.
@@ -43,7 +43,7 @@ public class MerchantRecipe implements Recipe {
     }
 
     public void addIngredient(ItemStack item) {
-        Preconditions.checkState(ingredients.size() < 2, "Merchant can only have 2 ingredients");
+        Preconditions.checkState(ingredients.size() < 2, "MerchantRecipe can only have 2 ingredients");
         ingredients.add(item.clone());
     }
 
@@ -88,7 +88,7 @@ public class MerchantRecipe implements Recipe {
      * Get the maximum number of uses this trade has.
      * <br>
      * The maximum uses of this trade may increase when a player trades with the
-     * owning villager.
+     * owning merchant.
      *
      * @return the maximum number of uses
      */