SPIGOT-2272: Add API for virtual Merchants

7 files changed, 113 insertions, 65 deletions

diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
index 093aec25..ce6b761d 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -29,6 +29,7 @@ import org.bukkit.help.HelpMap;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.map.MapView;
 import org.bukkit.permissions.Permissible;
@@ -932,6 +933,17 @@ public final class Bukkit {
     }
 
     /**
+     * Creates an empty merchant.
+     *
+     * @param title the title of the corresponding merchant inventory, displayed
+     * when the merchant inventory is viewed
+     * @return a new merchant
+     */
+    public static Merchant createMerchant(String title) {
+        return server.createMerchant(title);
+    }
+
+    /**
      * Gets user-specified limit for number of monsters that can spawn in a
      * chunk.
      *
diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index 480d873e..c25fe223 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -29,6 +29,7 @@ import org.bukkit.help.HelpMap;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.map.MapView;
 import org.bukkit.permissions.Permissible;
@@ -762,6 +763,15 @@ public interface Server extends PluginMessageRecipient {
     Inventory createInventory(InventoryHolder owner, int size, String title) throws IllegalArgumentException;
 
     /**
+     * Creates an empty merchant.
+     *
+     * @param title the title of the corresponding merchant inventory, displayed
+     * when the merchant inventory is viewed
+     * @return a new merchant
+     */
+    Merchant createMerchant(String title);
+
+    /**
      * Gets user-specified limit for number of monsters that can spawn in a
      * chunk.
      *
diff --git a/src/main/java/org/bukkit/entity/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java
index d0e0acf8..ede84ef9 100644
--- a/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/src/main/java/org/bukkit/entity/HumanEntity.java
@@ -3,6 +3,7 @@ package org.bukkit.entity;
 import org.bukkit.GameMode;
 import org.bukkit.Location;
 import org.bukkit.inventory.MainHand;
+import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.InventoryView;
@@ -118,6 +119,19 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
     public InventoryView openMerchant(Villager trader, boolean force);
 
     /**
+     * Starts a trade between the player and the merchant.
+     *
+     * Note that only one player may trade with a merchant at once. You must use
+     * the force parameter for this.
+     *
+     * @param merchant The merchant to trade with. Cannot be null.
+     * @param force whether to force the trade even if another player is trading
+     * @return The newly opened inventory view, or null if it could not be
+     * opened.
+     */
+    public InventoryView openMerchant(Merchant merchant, boolean force);
+
+    /**
      * Force-closes the currently open inventory view for this player, if any.
      */
     public void closeInventory();
diff --git a/src/main/java/org/bukkit/entity/Villager.java b/src/main/java/org/bukkit/entity/Villager.java
index 2244147f..8fc69da0 100644
--- a/src/main/java/org/bukkit/entity/Villager.java
+++ b/src/main/java/org/bukkit/entity/Villager.java
@@ -1,14 +1,13 @@
 package org.bukkit.entity;
 
-import java.util.List;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
-import org.bukkit.inventory.MerchantRecipe;
+import org.bukkit.inventory.Merchant;
 
 /**
  * Represents a villager NPC
  */
-public interface Villager extends Ageable, NPC, InventoryHolder {
+public interface Villager extends Ageable, NPC, InventoryHolder, Merchant {
 
     /**
      * Gets the current profession of this villager.
@@ -25,48 +24,6 @@ public interface Villager extends Ageable, NPC, InventoryHolder {
     public void setProfession(Profession profession);
 
     /**
-     * Get a list of trades currently available from this villager.
-     *
-     * @return an immutable list of trades
-     */
-    List<MerchantRecipe> getRecipes();
-
-    /**
-     * Set the list of trades currently available from this villager.
-     * <br>
-     * This will not change the selected trades of players currently trading
-     * with this villager.
-     *
-     * @param recipes a list of recipes
-     */
-    void setRecipes(List<MerchantRecipe> recipes);
-
-    /**
-     * Get the recipe at a certain index of this villager'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 villager'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 villager currently has available.
-     *
-     * @return the recipe count
-     */
-    int getRecipeCount();
-
-    /**
      * Gets this villager's inventory.
      * <br>
      * Note that this inventory is not the Merchant inventory, rather, it is the
@@ -78,21 +35,6 @@ public interface Villager extends Ageable, NPC, InventoryHolder {
     Inventory getInventory();
 
     /**
-     * Gets whether this villager is currently trading.
-     *
-     * @return whether the villager is trading
-     */
-    boolean isTrading();
-
-    /**
-     * Gets the player this villager is trading with, or null if it is not
-     * currently trading.
-     *
-     * @return the trader, or null
-     */
-    HumanEntity getTrader();
-
-    /**
      * Gets this villager's riches, the number of emeralds this villager has
      * been given.
      *
diff --git a/src/main/java/org/bukkit/inventory/Merchant.java b/src/main/java/org/bukkit/inventory/Merchant.java
new file mode 100644
index 00000000..c8e68570
--- /dev/null
+++ b/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();
+}
diff --git a/src/main/java/org/bukkit/inventory/MerchantInventory.java b/src/main/java/org/bukkit/inventory/MerchantInventory.java
index d51fdbda..f4eb3408 100644
--- a/src/main/java/org/bukkit/inventory/MerchantInventory.java
+++ b/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 {
 
diff --git a/src/main/java/org/bukkit/inventory/MerchantRecipe.java b/src/main/java/org/bukkit/inventory/MerchantRecipe.java
index 0a9fb637..9a03d20e 100644
--- a/src/main/java/org/bukkit/inventory/MerchantRecipe.java
+++ b/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
      */