SPIGOT-3981: Make custom inventories return specialised types where practical.

3 files changed, 93 insertions, 8 deletions

diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
index a3eafe70..bdd5a753 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -861,13 +861,27 @@ public final class Bukkit {
     }
 
     /**
-     * Creates an empty inventory of the specified type. If the type is {@link
-     * InventoryType#CHEST}, the new inventory has a size of 27; otherwise the
-     * new inventory has the normal size for its type.
+     * Creates an empty inventory with the specified type and title. If the type
+     * is {@link InventoryType#CHEST}, the new inventory has a size of 27;
+     * otherwise the new inventory has the normal size for its type.<br>
+     * It should be noted that some inventory types do not support titles and
+     * may not render with said titles on the Minecraft client.
+     * <br>
+     * {@link InventoryType#WORKBENCH} will not process crafting recipes if
+     * created with this method. Use
+     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * <br>
+     * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
+     * for possible enchanting results. Use
+     * {@link Player#openEnchanting(Location, boolean)} instead.
      *
      * @param owner the holder of the inventory, or null to indicate no holder
      * @param type the type of inventory to create
      * @return a new inventory
+     * @throws IllegalArgumentException if the {@link InventoryType} cannot be
+     * viewed.
+     *
+     * @see InventoryType#isCreatable()
      */
     public static Inventory createInventory(InventoryHolder owner, InventoryType type) {
         return server.createInventory(owner, type);
@@ -879,11 +893,23 @@ public final class Bukkit {
      * otherwise the new inventory has the normal size for its type.<br>
      * It should be noted that some inventory types do not support titles and
      * may not render with said titles on the Minecraft client.
+     * <br>
+     * {@link InventoryType#WORKBENCH} will not process crafting recipes if
+     * created with this method. Use
+     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * <br>
+     * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
+     * for possible enchanting results. Use
+     * {@link Player#openEnchanting(Location, boolean)} instead.
      *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param type The type of inventory to create.
      * @param title The title of the inventory, to be displayed when it is viewed.
      * @return The new inventory.
+     * @throws IllegalArgumentException if the {@link InventoryType} cannot be
+     * viewed.
+     *
+     * @see InventoryType#isCreatable()
      */
     public static Inventory createInventory(InventoryHolder owner, InventoryType type, String title) {
         return server.createInventory(owner, type, title);
diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index d69fa6a9..4daee3b0 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -701,13 +701,27 @@ public interface Server extends PluginMessageRecipient {
     public HelpMap getHelpMap();
 
     /**
-     * Creates an empty inventory of the specified type. If the type is {@link
-     * InventoryType#CHEST}, the new inventory has a size of 27; otherwise the
-     * new inventory has the normal size for its type.
+     * Creates an empty inventory with the specified type and title. If the type
+     * is {@link InventoryType#CHEST}, the new inventory has a size of 27;
+     * otherwise the new inventory has the normal size for its type.<br>
+     * It should be noted that some inventory types do not support titles and
+     * may not render with said titles on the Minecraft client.
+     * <br>
+     * {@link InventoryType#WORKBENCH} will not process crafting recipes if
+     * created with this method. Use
+     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * <br>
+     * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
+     * for possible enchanting results. Use
+     * {@link Player#openEnchanting(Location, boolean)} instead.
      *
      * @param owner the holder of the inventory, or null to indicate no holder
      * @param type the type of inventory to create
      * @return a new inventory
+     * @throws IllegalArgumentException if the {@link InventoryType} cannot be
+     * viewed.
+     *
+     * @see InventoryType#isCreatable()
      */
     Inventory createInventory(InventoryHolder owner, InventoryType type);
 
@@ -717,11 +731,23 @@ public interface Server extends PluginMessageRecipient {
      * otherwise the new inventory has the normal size for its type.<br>
      * It should be noted that some inventory types do not support titles and
      * may not render with said titles on the Minecraft client.
+     * <br>
+     * {@link InventoryType#WORKBENCH} will not process crafting recipes if
+     * created with this method. Use
+     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * <br>
+     * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
+     * for possible enchanting results. Use
+     * {@link Player#openEnchanting(Location, boolean)} instead.
      *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param type The type of inventory to create.
      * @param title The title of the inventory, to be displayed when it is viewed.
      * @return The new inventory.
+     * @throws IllegalArgumentException if the {@link InventoryType} cannot be
+     * viewed.
+     *
+     * @see InventoryType#isCreatable()
      */
     Inventory createInventory(InventoryHolder owner, InventoryType type, String title);
 
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryType.java b/src/main/java/org/bukkit/event/inventory/InventoryType.java
index f6446392..a5314710 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryType.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryType.java
@@ -1,5 +1,22 @@
 package org.bukkit.event.inventory;
 
+import org.bukkit.inventory.InventoryHolder;
+
+/**
+ * Represents the different kinds of inventories available in Bukkit.
+ * <br>
+ * Only InventoryTypes marked {@link #isCreatable()} can be created.
+ * <br>
+ * The current list of inventories that cannot be created via
+ * {@link org.bukkit.Bukkit#createInventory} are:<br>
+ * <blockquote>
+ *     {@link InventoryType#CREATIVE} and {@link InventoryType#CRAFTING}
+ * </blockquote>
+ *
+ * See {@link org.bukkit.Bukkit#createInventory} for more information.
+ *
+ * @see org.bukkit.Bukkit#createInventory(InventoryHolder, InventoryType)
+ */
 public enum InventoryType {
 
     /**
@@ -28,7 +45,7 @@ public enum InventoryType {
      * A player's crafting inventory, with 4 CRAFTING slots and a RESULT slot.
      * Also implies that the 4 ARMOR slots are accessible.
      */
-    CRAFTING(5,"Crafting"),
+    CRAFTING(5,"Crafting", false),
     /**
      * An enchantment table inventory, with two CRAFTING slots and three
      * enchanting buttons.
@@ -49,7 +66,7 @@ public enum InventoryType {
      * else. (The actual creative interface with the items is client-side and
      * cannot be altered by the server.)
      */
-    CREATIVE(9,"Creative"),
+    CREATIVE(9,"Creative", false),
     /**
      * The merchant inventory, with 2 TRADE-IN slots, and 1 RESULT slot.
      */
@@ -78,10 +95,16 @@ public enum InventoryType {
 
     private final int size;
     private final String title;
+    private final boolean isCreatable;
 
     private InventoryType(int defaultSize, String defaultTitle) {
+        this(defaultSize, defaultTitle, true);
+    }
+
+    private InventoryType(int defaultSize, String defaultTitle, boolean isCreatable) {
         size = defaultSize;
         title = defaultTitle;
+        this.isCreatable = isCreatable;
     }
 
     public int getDefaultSize() {
@@ -92,6 +115,16 @@ public enum InventoryType {
         return title;
     }
 
+    /**
+     * Denotes that this InventoryType can be created via the normal
+     * {@link org.bukkit.Bukkit#createInventory} methods.
+     *
+     * @return if this InventoryType can be created and shown to a player
+     */
+    public boolean isCreatable() {
+        return isCreatable;
+    }
+
     public enum SlotType {
         /**
          * A result slot in a furnace or crafting inventory.