[Bleeding] Inventory framework and events. Addresses BUKKIT-856

New events:
- InventoryOpenEvent
- InventoryClickEvent - detects any clicks on a slot or outside the window
  - In the creative inventory view, only clicks on the quickbar are detected
- InventoryCloseEvent
- BrewEvent - when a potion finishes brewing
- CraftItemEvent (a subevent of InventoryClickEvent) - fired when taking the crafted item
- PrepareItemCraftEvent - fired just before updating the result slot
Changes to existing events:
- EnchantItemEvent extends InventoryEvent and also has a new whichButton() method
- PrepareItemEnchantEvent also extends InventoryEvent
- FurnaceBurnEvent and FurnaceSmeltEvent now extend BlockEvent (as does BrewEvent)
- PlayerInventoryEvent is deprecated (though it never did anything anyway)
New subclasses of Inventory:
- BrewerInventory
- CraftingInventory
- DoubleChestInventory
- EnchantingInventory
- FurnaceInventory
New methods in Inventory:
- getViewers()
- getTitle()
- getType()
- getHolder()
- iterator() - Yes, inventories are now iterable!
  - The iterator is a ListIterator that does not support add or remove
New methods in Player:
- getOpenInventory()
- openInventory()
- openWorkbench()
- openEnchanting()
- closeInventory()
- setWindowProperty()
- getItemOnCursor()
- setItemOnCursor()
Other changes:
- createInventory() methods in Server to make inventories not linked to an object
- ContainerBlock is deprecated in favour of InventoryHolder
- New InventoryView class gives direct access to an inventory window!
- Removed the Slot class which did nothing and was used nowhere

Some small credit goes to Afforess (initial conception of openInventory() methods) and Drakia (initial conception of InventoryOpenEvent and InventoryCloseEvent).

10 files changed, 363 insertions, 30 deletions

diff --git a/src/main/java/org/bukkit/inventory/BrewerInventory.java b/src/main/java/org/bukkit/inventory/BrewerInventory.java
new file mode 100644
index 00000000..a3ebf069
--- /dev/null
+++ b/src/main/java/org/bukkit/inventory/BrewerInventory.java
@@ -0,0 +1,18 @@
+package org.bukkit.inventory;
+
+import org.bukkit.block.BrewingStand;
+
+public interface BrewerInventory extends Inventory {
+    /**
+     * Get the current ingredient for brewing.
+     * @return The ingredient.
+     */
+    ItemStack getIngredient();
+    /**
+     * Set the current ingredient for brewing.
+     * @param ingredient The ingredient
+     */
+    void setIngredient(ItemStack ingredient);
+
+    BrewingStand getHolder();
+}
diff --git a/src/main/java/org/bukkit/inventory/CraftingInventory.java b/src/main/java/org/bukkit/inventory/CraftingInventory.java
new file mode 100644
index 00000000..9c1a0c1e
--- /dev/null
+++ b/src/main/java/org/bukkit/inventory/CraftingInventory.java
@@ -0,0 +1,33 @@
+package org.bukkit.inventory;
+
+/**
+ * Interface to the crafting inventories
+ */
+public interface CraftingInventory extends Inventory {
+    /**
+     * Check what item is in the result slot of this crafting inventory.
+     * @return The result item.
+     */
+    ItemStack getResult();
+    /**
+     * Get the contents of the crafting matrix.
+     * @return The contents.
+     */
+    ItemStack[] getMatrix();
+    /**
+     * Set the item in the result slot of the crafting inventory.
+     * @param newResult The new result item.
+     */
+    void setResult(ItemStack newResult);
+    /**
+     * Replace the contents of the crafting matrix
+     * @param contents The new contents.
+     * @throws IllegalArgumentException if the length of contents is greater than the size of the crafting matrix.
+     */
+    void setMatrix(ItemStack[] contents);
+    /**
+     * Get the current recipe formed on the crafting inventory, if any.
+     * @return The recipe, or null if the current contents don't match any recipe.
+     */
+    Recipe getRecipe();
+}
\ No newline at end of file
diff --git a/src/main/java/org/bukkit/inventory/DoubleChestInventory.java b/src/main/java/org/bukkit/inventory/DoubleChestInventory.java
new file mode 100644
index 00000000..81d60304
--- /dev/null
+++ b/src/main/java/org/bukkit/inventory/DoubleChestInventory.java
@@ -0,0 +1,15 @@
+package org.bukkit.inventory;
+
+public interface DoubleChestInventory extends Inventory {
+    /**
+     * Get the left half of this double chest.
+     * @return The left side inventory
+     */
+    Inventory getLeftSide();
+
+    /**
+     * Get the right side of this double chest.
+     * @return The right side inventory
+     */
+    Inventory getRightSide();
+}
diff --git a/src/main/java/org/bukkit/inventory/EnchantingInventory.java b/src/main/java/org/bukkit/inventory/EnchantingInventory.java
new file mode 100644
index 00000000..40e85946
--- /dev/null
+++ b/src/main/java/org/bukkit/inventory/EnchantingInventory.java
@@ -0,0 +1,14 @@
+package org.bukkit.inventory;
+
+public interface EnchantingInventory extends Inventory {
+    /**
+     * Set the item being enchanted.
+     * @param item The new item
+     */
+    void setItem(ItemStack item);
+    /**
+     * Get the item being enchanted.
+     * @return The current item.
+     */
+    ItemStack getItem();
+}
diff --git a/src/main/java/org/bukkit/inventory/FurnaceInventory.java b/src/main/java/org/bukkit/inventory/FurnaceInventory.java
new file mode 100644
index 00000000..fb3246f4
--- /dev/null
+++ b/src/main/java/org/bukkit/inventory/FurnaceInventory.java
@@ -0,0 +1,43 @@
+package org.bukkit.inventory;
+
+import org.bukkit.block.Furnace;
+
+public interface FurnaceInventory extends Inventory {
+    /**
+     * Get the current item in the result slot.
+     * @return The item
+     */
+    ItemStack getResult();
+
+    /**
+     * Get the current fuel.
+     * @return The item
+     */
+    ItemStack getFuel();
+
+    /**
+     * Get the item currently smelting.
+     * @return The item
+     */
+    ItemStack getSmelting();
+
+    /**
+     * Set the current fuel.
+     * @param stack The item
+     */
+    void setFuel(ItemStack stack);
+
+    /**
+     * Set the current item in the result slot.
+     * @param stack The item
+     */
+    void setResult(ItemStack stack);
+
+    /**
+     * Set the item currently smelting.
+     * @param stack The item
+     */
+    void setSmelting(ItemStack stack);
+
+    Furnace getHolder();
+}
diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java
index 2a276246..b42ffe21 100644
--- a/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/src/main/java/org/bukkit/inventory/Inventory.java
@@ -1,12 +1,17 @@
 package org.bukkit.inventory;
 
 import java.util.HashMap;
+import java.util.List;
+import java.util.ListIterator;
+
 import org.bukkit.Material;
+import org.bukkit.entity.HumanEntity;
+import org.bukkit.event.inventory.InventoryType;
 
 /**
  * Interface to the various inventories
  */
-public interface Inventory {
+public interface Inventory extends Iterable<ItemStack> {
 
     /**
      * Returns the size of the inventory
@@ -69,7 +74,8 @@ public interface Inventory {
     /**
      * Set the inventory's contents
      *
-     * @param items A complete replacement for the contents; the length must be equal to {@link #getSize()}.
+     * @param items A complete replacement for the contents; the length must be less than or equal to {@link #getSize()}.
+     * @throws IllegalArgumentException If the array has more items than the inventory.
      */
     public void setContents(ItemStack[] items);
 
@@ -216,4 +222,34 @@ public interface Inventory {
      * Clear out the whole index
      */
     public void clear();
+
+    /**
+     * Get a list of players viewing. Note that a player is considered to be viewing their own
+     * inventory and internal crafting screen even when said inventory is not open. They will normally
+     * be considered to be viewing their inventory even when they have a different inventory screen open,
+     * but it's possible for customized inventory screens to exclude the viewer's inventory, so this should
+     * never be assumed to be non-empty.
+     * @return A list of players.
+     */
+    public List<HumanEntity> getViewers();
+
+    /**
+     * Get the title of this inventory.
+     * @return The title.
+     */
+    public String getTitle();
+
+    /**
+     * Check what type of inventory this is.
+     * @return The type of inventory.
+     */
+    public InventoryType getType();
+
+    /**
+     * Gets the block or entity belonging to the open inventory
+     * @return The holder of the inventory; null if it has no holder.
+     */
+    public InventoryHolder getHolder();
+
+    public ListIterator<ItemStack> iterator();
 }
diff --git a/src/main/java/org/bukkit/inventory/InventoryHolder.java b/src/main/java/org/bukkit/inventory/InventoryHolder.java
new file mode 100644
index 00000000..9d788438
--- /dev/null
+++ b/src/main/java/org/bukkit/inventory/InventoryHolder.java
@@ -0,0 +1,10 @@
+package org.bukkit.inventory;
+
+public interface InventoryHolder {
+    /**
+     * Get the object's inventory.
+     *
+     * @return The inventory.
+     */
+    public Inventory getInventory();
+}
diff --git a/src/main/java/org/bukkit/inventory/InventoryView.java b/src/main/java/org/bukkit/inventory/InventoryView.java
new file mode 100644
index 00000000..fd2c4080
--- /dev/null
+++ b/src/main/java/org/bukkit/inventory/InventoryView.java
@@ -0,0 +1,188 @@
+package org.bukkit.inventory;
+
+import org.bukkit.entity.HumanEntity;
+import org.bukkit.event.inventory.InventoryType;
+
+/**
+ * Represents a view linking two inventories and a single player
+ * (whose inventory may or may not be one of the two)
+ *
+ * Note: If you implement this interface but fail to satisfy the expected
+ * contracts of certain methods, there's no guarantee that the game
+ * will work as it should.
+ */
+public abstract class InventoryView {
+    public final static int OUTSIDE = -999;
+    /**
+     * Represents various extra properties of certai inventory windows.
+     */
+    public enum Property {
+        /**
+         * The progress of the down-pointing arrow in a brewing inventory.
+         */
+        BREW_TIME(0, InventoryType.BREWING),
+        /**
+         * The progress of the right-pointing arrow in a furnace inventory.
+         */
+        COOK_TIME(0, InventoryType.FURNACE),
+        /**
+         * The progress of the flame in a furnace inventory.
+         */
+        BURN_TIME(1, InventoryType.FURNACE),
+        /**
+         * How many total ticks the current fuel should last.
+         */
+        TICKS_FOR_CURRENT_FUEL(2, InventoryType.FURNACE),
+        /**
+         * In an enchanting inventory, the top button's experience level value.
+         */
+        ENCHANT_BUTTON1(0, InventoryType.ENCHANTING),
+        /**
+         * In an enchanting inventory, the middle button's experience level value.
+         */
+        ENCHANT_BUTTON2(1, InventoryType.ENCHANTING),
+        /**
+         * In an enchanting inventory, the bottom button's experience level value.
+         */
+        ENCHANT_BUTTON3(2, InventoryType.ENCHANTING);
+        int id;
+        InventoryType style;
+        private Property(int id, InventoryType appliesTo) {
+            this.id = id;
+            style = appliesTo;
+        }
+
+        public InventoryType getType() {
+            return style;
+        }
+
+        public int getId() {
+            return id;
+        }
+    }
+    /**
+     * Get the upper inventory involved in this transaction.
+     * @return the inventory
+     */
+    public abstract Inventory getTopInventory();
+
+    /**
+     * Get the lower inventory involved in this transaction.
+     * @return the inventory
+     */
+    public abstract Inventory getBottomInventory();
+
+    /**
+     * Get the player viewing.
+     * @return the player
+     */
+    public abstract HumanEntity getPlayer();
+
+    /**
+     * Determine the type of inventory involved in the transaction. This indicates
+     * the window style being shown. It will never return PLAYER, since that is
+     * common to all windows.
+     * @return the inventory type
+     */
+    public abstract InventoryType getType();
+
+    /**
+     * Sets one item in this inventory view by its raw slot ID.
+     * @param slot The ID as returned by InventoryClickEvent.getRawSlot()
+     * @param item The new item to put in the slot, or null to clear it.
+     */
+    public void setItem(int slot, ItemStack item) {
+        if (slot != OUTSIDE) {
+            if (slot < getTopInventory().getSize()) {
+                getTopInventory().setItem(convertSlot(slot),item);
+            } else {
+                getBottomInventory().setItem(convertSlot(slot),item);
+            }
+        }
+    }
+
+    /**
+     * Sets one item in this inventory view by its raw slot ID.
+     * @param slot The ID as returned by InventoryClickEvent.getRawSlot()
+     * @return The item currently in the slot.
+     */
+    public ItemStack getItem(int slot) {
+        if (slot == OUTSIDE) {
+            return null;
+        }
+        if (slot < getTopInventory().getSize()) {
+            return getTopInventory().getItem(convertSlot(slot));
+        } else {
+            return getBottomInventory().getItem(convertSlot(slot));
+        }
+    }
+
+    /**
+     * Sets the item on the cursor of one of the viewing players.
+     * @param item The item to put on the cursor, or null to remove the item on their cursor.
+     */
+    public final void setCursor(ItemStack item) {
+        getPlayer().setItemOnCursor(item);
+    }
+
+    /**
+     * Get the item on the cursor of one of the viewing players.
+     * @return The item on the player's cursor, or null if they aren't holding one.
+     */
+    public final ItemStack getCursor() {
+        return getPlayer().getItemOnCursor();
+    }
+
+    /**
+     * Converts a raw slot ID into its local slot ID into whichever of the two inventories
+     * the slot points to. If the raw slot refers to the upper inventory, it will be returned
+     * unchanged and thus be suitable for getTopInventory().getItem(); if it refers to the
+     * lower inventory, the output will differ from the input and be suitable for
+     * getBottomInventory().getItem().
+     * @param rawSlot The raw slot ID.
+     * @return The converted slot ID.
+     */
+    public final int convertSlot(int rawSlot) {
+        int numInTop = getTopInventory().getSize();
+        if (rawSlot < numInTop) {
+            return rawSlot;
+        }
+        int slot = rawSlot - numInTop;
+        if (getType() == InventoryType.CRAFTING) {
+            if(slot < 4) return 39 - slot;
+            else slot -= 4;
+        }
+        if (slot >= 27) slot -= 27;
+        else slot += 9;
+        return slot;
+    }
+
+    /**
+     * Closes the inventory view.
+     */
+    public final void close() {
+        getPlayer().closeInventory();
+    }
+
+    /**
+     * Check the total number of slots in this view, combining the upper and lower inventories.
+     * Note though that it's possible for this to be greater than the sum of the two inventories
+     * if for example some slots are not being used.
+     * @return The total size
+     */
+    public final int countSlots() {
+        return getTopInventory().getSize() + getBottomInventory().getSize();
+    }
+
+    public final boolean setProperty(Property prop, int value) {
+        return getPlayer().setWindowProperty(prop, value);
+    }
+
+    /**
+     * Get the title of this inventory window.
+     * @return The title.
+     */
+    public final String getTitle() {
+        return getTopInventory().getTitle();
+    }
+}
diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
index e5f797a0..57221091 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -1,5 +1,7 @@
 package org.bukkit.inventory;
 
+import org.bukkit.entity.HumanEntity;
+
 /**
  * Includes interface to the 4 armor slots
  */
@@ -99,4 +101,6 @@ public interface PlayerInventory extends Inventory {
      * @return Held item slot number
      */
     public int getHeldItemSlot();
+
+    public HumanEntity getHolder();
 }
diff --git a/src/main/java/org/bukkit/inventory/Slot.java b/src/main/java/org/bukkit/inventory/Slot.java
deleted file mode 100644
index 0e546ca6..00000000
--- a/src/main/java/org/bukkit/inventory/Slot.java
+++ /dev/null
@@ -1,28 +0,0 @@
-package org.bukkit.inventory;
-
-/**
- * Represents a slot in an inventory
- */
-public interface Slot {
-
-    /**
-     * Gets the inventory this slot belongs to
-     *
-     * @return The inventory
-     */
-    public Inventory getInventory();
-
-    /**
-     * Get the index this slot belongs to
-     *
-     * @return Index of the slot
-     */
-    public int getIndex();
-
-    /**
-     * Get the item from the slot.
-     *
-     * @return ItemStack in the slot.
-     */
-    public ItemStack getItem();
-}