SPIGOT-1526 / SPIGOT-1809: Expand Inventory API

2 files changed, 43 insertions, 1 deletions

diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java
index 32838403..5832e245 100644
--- a/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/src/main/java/org/bukkit/inventory/Inventory.java
@@ -128,6 +128,28 @@ public interface Inventory extends Iterable<ItemStack> {
     public void setContents(ItemStack[] items) throws IllegalArgumentException;
 
     /**
+     * Return the contents from the section of the inventory where items can
+     * reasonably be expected to be stored. In most cases this will represent
+     * the entire inventory, but in some cases it may exclude armor or result
+     * slots.
+     * <br>
+     * It is these contents which will be used for add / contains / remove
+     * methods which look for a specific stack.
+     *
+     * @return inventory storage contents
+     */
+    public ItemStack[] getStorageContents();
+
+    /**
+     * Put the given ItemStacks into the storage slots
+     *
+     * @param items The ItemStacks to use as storage contents
+     * @throws IllegalArgumentException If the array has more items than the
+     * inventory.
+     */
+    public void setStorageContents(ItemStack[] items) throws IllegalArgumentException;
+
+    /**
      * Checks if the inventory contains any ItemStacks with the given
      * materialId
      *
diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
index f475bba7..557cc04d 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -3,7 +3,7 @@ package org.bukkit.inventory;
 import org.bukkit.entity.HumanEntity;
 
 /**
- * Interface to the inventory of a Player, including the four armor slots.
+ * Interface to the inventory of a Player, including the four armor slots and any extra slots.
  */
 public interface PlayerInventory extends Inventory {
 
@@ -15,6 +15,17 @@ public interface PlayerInventory extends Inventory {
     public ItemStack[] getArmorContents();
 
     /**
+     * Get all additional ItemStacks stored in this inventory.
+     * <br>
+     * NB: What defines an extra slot is up to the implementation, however it
+     * will not be contained within {@link #getStorageContents()} or
+     * {@link #getArmorContents()}
+     *
+     * @return All additional ItemStacks
+     */
+    public ItemStack[] getExtraContents();
+
+    /**
      * Return the ItemStack from the helmet slot
      *
      * @return The ItemStack in the helmet slot
@@ -74,6 +85,15 @@ public interface PlayerInventory extends Inventory {
     public void setArmorContents(ItemStack[] items);
 
     /**
+     * Put the given ItemStacks into the extra slots
+     * <br>
+     * See {@link #getExtraContents()} for an explanation of extra slots.
+     *
+     * @param items The ItemStacks to use as extra
+     */
+    public void setExtraContents(ItemStack[] items);
+
+    /**
      * Put the given ItemStack into the helmet slot. This does not check if
      * the ItemStack is a helmet
      *