Improvements to BlockStates

* Update Javadoc of block state classes to better match implementation behaviour.
* Add Container interface which provides access to the snapshot inventory.

By: Lukas Hennig <lukas@wirsindwir.de>

paper-api/src/main/java/org/bukkit/block/Dispenser.java

@@ -1,29 +1,32 @@
 package org.bukkit.block;
 
 import org.bukkit.Nameable;
-import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.projectiles.BlockProjectileSource;
 
 /**
- * Represents a dispenser.
+ * Represents a captured state of a dispenser.
  */
-public interface Dispenser extends BlockState, InventoryHolder, Lockable, Nameable {
+public interface Dispenser extends Container, Nameable {
 
     /**
-     * Gets the BlockProjectileSource object for this dispenser.
+     * Gets the BlockProjectileSource object for the dispenser.
      * <p>
-     * If the block is no longer a dispenser, this will return null.
+     * If the block represented by this state is no longer a dispenser, this
+     * will return null.
      *
      * @return a BlockProjectileSource if valid, otherwise null
+     * @throws IllegalStateException if this block state is not placed
      */
     public BlockProjectileSource getBlockProjectileSource();
 
     /**
-     * Attempts to dispense the contents of this block.
+     * Attempts to dispense the contents of the dispenser.
      * <p>
-     * If the block is no longer a dispenser, this will return false.
+     * If the block represented by this state is no longer a dispenser, this
+     * will return false.
      *
      * @return true if successful, otherwise false
+     * @throws IllegalStateException if this block state is not placed
      */
     public boolean dispense();
 }