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/Banner.java

@@ -5,6 +5,9 @@ import org.bukkit.block.banner.Pattern;
 
 import java.util.List;
 
+/**
+ * Represents a captured state of a banner.
+ */
 public interface Banner extends BlockState {
 
     /**

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

@@ -3,19 +3,29 @@ package org.bukkit.block;
 import java.util.Collection;
 import org.bukkit.Nameable;
 import org.bukkit.entity.LivingEntity;
-import org.bukkit.inventory.InventoryHolder;
+import org.bukkit.inventory.BeaconInventory;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
 
 /**
- * Represents a beacon.
+ * Represents a captured state of a beacon.
  */
-public interface Beacon extends BlockState, InventoryHolder, Lockable, Nameable {
+public interface Beacon extends Container, Nameable {
+
+    @Override
+    BeaconInventory getInventory();
+
+    @Override
+    BeaconInventory getSnapshotInventory();
 
     /**
      * Returns the list of players within the beacon's range of effect.
+     * <p>
+     * This will return an empty list if the block represented by this state is
+     * no longer a beacon.
      *
      * @return the players in range
+     * @throws IllegalStateException if this block state is not placed
      */
     Collection<LivingEntity> getEntitiesInRange();
 

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

@@ -3,6 +3,6 @@ package org.bukkit.block;
 import org.bukkit.material.Colorable;
 
 /**
- * Represents a bed.
+ * Represents a captured state of a bed.
  */
 public interface Bed extends BlockState, Colorable { }

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

@@ -19,28 +19,29 @@ import org.bukkit.metadata.Metadatable;
 public interface BlockState extends Metadatable {
 
     /**
-     * Gets the block represented by this BlockState
+     * Gets the block represented by this block state.
      *
-     * @return Block that this BlockState represents
+     * @return the block represented by this block state
+     * @throws IllegalStateException if this block state is not placed
      */
     Block getBlock();
 
     /**
-     * Gets the metadata for this block
+     * Gets the metadata for this block state.
      *
      * @return block specific metadata
      */
     MaterialData getData();
 
     /**
-     * Gets the type of this block
+     * Gets the type of this block state.
      *
      * @return block type
      */
     Material getType();
 
     /**
-     * Gets the type-id of this block
+     * Gets the type-id of this block state.
      *
      * @return block type-id
      * @deprecated Magic value
@@ -49,52 +50,58 @@ public interface BlockState extends Metadatable {
     int getTypeId();
 
     /**
-     * Gets the light level between 0-15
+     * Gets the current light level of the block represented by this block state.
      *
-     * @return light level
+     * @return the light level between 0-15
+     * @throws IllegalStateException if this block state is not placed
      */
     byte getLightLevel();
 
     /**
-     * Gets the world which contains this Block
+     * Gets the world which contains the block represented by this block state.
      *
-     * @return World containing this block
+     * @return the world containing the block represented by this block state
+     * @throws IllegalStateException if this block state is not placed
      */
     World getWorld();
 
     /**
-     * Gets the x-coordinate of this block
+     * Gets the x-coordinate of this block state.
      *
      * @return x-coordinate
      */
     int getX();
 
     /**
-     * Gets the y-coordinate of this block
+     * Gets the y-coordinate of this block state.
      *
      * @return y-coordinate
      */
     int getY();
 
     /**
-     * Gets the z-coordinate of this block
+     * Gets the z-coordinate of this block state.
      *
      * @return z-coordinate
      */
     int getZ();
 
     /**
-     * Gets the location of this block
+     * Gets the location of this block state.
+     * <p>
+     * If this block state is not placed the location's world will be null!
      *
-     * @return location
+     * @return the location
      */
     Location getLocation();
 
     /**
-     * Stores the location of this block in the provided Location object.
+     * Stores the location of this block state in the provided Location object.
      * <p>
      * If the provided Location is null this method does nothing and returns
      * null.
+     * <p>
+     * If this block state is not placed the location's world will be null!
      *
      * @param loc the location to copy into
      * @return The Location object provided or null
@@ -102,30 +109,31 @@ public interface BlockState extends Metadatable {
     Location getLocation(Location loc);
 
     /**
-     * Gets the chunk which contains this block
+     * Gets the chunk which contains the block represented by this block state.
      *
-     * @return Containing Chunk
+     * @return the containing Chunk
+     * @throws IllegalStateException if this block state is not placed
      */
     Chunk getChunk();
 
     /**
-     * Sets the metadata for this block
+     * Sets the metadata for this block state.
      *
      * @param data New block specific metadata
      */
     void setData(MaterialData data);
 
     /**
-     * Sets the type of this block
+     * Sets the type of this block state.
      *
-     * @param type Material to change this block to
+     * @param type Material to change this block state to
      */
     void setType(Material type);
 
     /**
-     * Sets the type-id of this block
+     * Sets the type-id of this block state.
      *
-     * @param type Type-Id to change this block to
+     * @param type Type-Id to change this block state to
      * @return Whether it worked?
      * @deprecated Magic value
      */
@@ -162,6 +170,8 @@ public interface BlockState extends Metadatable {
      * Attempts to update the block represented by this state, setting it to
      * the new values as defined by this state.
      * <p>
+     * If this state is not placed, this will have no effect and return true.
+     * <p>
      * Unless force is true, this will not modify the state of a block if it
      * is no longer the same type as it was when this state was taken. It will
      * return false in this eventuality.
@@ -195,8 +205,8 @@ public interface BlockState extends Metadatable {
 
     /**
      * Returns whether this state is placed in the world.
-     *
-     * Some methods will not work if the blockState isn't
+     * <p>
+     * Some methods will not work if the block state isn't
      * placed in the world.
      *
      * @return whether the state is placed in the world

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

@@ -2,15 +2,14 @@ package org.bukkit.block;
 
 import org.bukkit.Nameable;
 import org.bukkit.inventory.BrewerInventory;
-import org.bukkit.inventory.InventoryHolder;
 
 /**
- * Represents a brewing stand.
+ * Represents a captured state of a brewing stand.
  */
-public interface BrewingStand extends BlockState, InventoryHolder, Lockable, Nameable {
+public interface BrewingStand extends Container, Nameable {
 
     /**
-     * How much time is left in the brewing cycle
+     * How much time is left in the brewing cycle.
      *
      * @return Brew Time
      */
@@ -37,5 +36,9 @@ public interface BrewingStand extends BlockState, InventoryHolder, Lockable, Nam
      */
     void setFuelLevel(int level);
 
-    public BrewerInventory getInventory();
+    @Override
+    BrewerInventory getInventory();
+
+    @Override
+    BrewerInventory getSnapshotInventory();
 }

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

@@ -2,18 +2,25 @@ package org.bukkit.block;
 
 import org.bukkit.Nameable;
 import org.bukkit.inventory.Inventory;
-import org.bukkit.inventory.InventoryHolder;
 
 /**
- * Represents a chest.
+ * Represents a captured state of a chest.
  */
-public interface Chest extends BlockState, InventoryHolder, Lockable, Nameable {
+public interface Chest extends Container, Nameable {
 
     /**
-     * Returns the chest's inventory. If this is a double chest, it returns
-     * just the portion of the inventory linked to this half of the chest.
+     * Gets the inventory of the chest block represented by this block state.
+     * <p>
+     * If the chest is a double chest, it returns just the portion of the
+     * inventory linked to the half of the chest corresponding to this block state.
+     * <p>
+     * If the block was changed to a different type in the meantime, the
+     * returned inventory might no longer be valid.
+     * <p>
+     * If this block state is not placed this will return the captured
+     * inventory snapshot instead.
      *
-     * @return The inventory.
+     * @return the inventory
      */
     Inventory getBlockInventory();
 }

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

@@ -1,5 +1,8 @@
 package org.bukkit.block;
 
+/**
+ * Represents a captured state of a command block.
+ */
 public interface CommandBlock extends BlockState {
 
     /**

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

@@ -1,6 +1,6 @@
 package org.bukkit.block;
 
 /**
- * Represents an on / off comparator.
+ * Represents a captured state of an on / off comparator.
  */
 public interface Comparator extends BlockState { }

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

@@ -0,0 +1,36 @@
+package org.bukkit.block;
+
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.InventoryHolder;
+
+/**
+ * Represents a captured state of a container block.
+ */
+public interface Container extends BlockState, InventoryHolder, Lockable {
+
+    /**
+     * Gets the inventory of the block represented by this block state.
+     * <p>
+     * If the block was changed to a different type in the meantime, the
+     * returned inventory might no longer be valid.
+     * <p>
+     * If this block state is not placed this will return the captured inventory
+     * snapshot instead.
+     *
+     * @return the inventory
+     */
+    @Override
+    Inventory getInventory();
+
+    /**
+     * Gets the captured inventory snapshot of this container.
+     * <p>
+     * The returned inventory is not linked to any block. Any modifications to
+     * the returned inventory will not be applied to the block represented by
+     * this block state up until {@link #update(boolean, boolean)} has been
+     * called.
+     *
+     * @return the captured inventory snapshot
+     */
+    Inventory getSnapshotInventory();
+}

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

@@ -3,7 +3,7 @@ package org.bukkit.block;
 import org.bukkit.entity.EntityType;
 
 /**
- * Represents a creature spawner.
+ * Represents a captured state of a creature spawner.
  */
 public interface CreatureSpawner extends BlockState {
 

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

@@ -1,6 +1,6 @@
 package org.bukkit.block;
 
 /**
- * Represents a (possibly inverted) daylight detector.
+ * Represents a captured state of a (possibly inverted) daylight detector.
  */
 public interface DaylightDetector extends BlockState { }

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();
 }

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

@@ -1,27 +1,31 @@
 package org.bukkit.block;
 
 import org.bukkit.Nameable;
-import org.bukkit.inventory.InventoryHolder;
 
 /**
- * Represents a dropper.
+ * Represents a captured state of a dropper.
  */
-public interface Dropper extends BlockState, InventoryHolder, Lockable, Nameable {
+public interface Dropper extends Container, Nameable {
 
     /**
-     * Tries to drop a randomly selected item from the Dropper's inventory,
-     * following the normal behavior of a Dropper.
+     * Tries to drop a randomly selected item from the dropper's inventory,
+     * following the normal behavior of a dropper.
      * <p>
-     * Normal behavior of a Dropper is as follows:
+     * Normal behavior of a dropper is as follows:
      * <p>
-     * If the block that the Dropper is facing is an InventoryHolder,
+     * If the block that the dropper is facing is an InventoryHolder,
      * the randomly selected ItemStack is placed within that 
      * Inventory in the first slot that's available, starting with 0 and
      * counting up.  If the inventory is full, nothing happens.
      * <p>
-     * If the block that the Dropper is facing is not an InventoryHolder,
+     * If the block that the dropper is facing is not an InventoryHolder,
      * the randomly selected ItemStack is dropped on
      * the ground in the form of an {@link org.bukkit.entity.Item Item}.
+     * <p>
+     * If the block represented by this state is no longer a dropper, this will
+     * do nothing.
+     * 
+     * @throws IllegalStateException if this block state is not placed
      */
     public void drop();
 }

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

@@ -3,6 +3,6 @@ package org.bukkit.block;
 import org.bukkit.Nameable;
 
 /**
- * Represents an enchanting table.
+ * Represents a captured state of an enchanting table.
  */
 public interface EnchantingTable extends BlockState, Nameable { }

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

@@ -3,13 +3,15 @@ package org.bukkit.block;
 import org.bukkit.Location;
 
 /**
- * Represents an end gateway.
+ * Represents a captured state of an end gateway.
  */
 public interface EndGateway extends BlockState {
 
     /**
      * Gets the location that entities are teleported to when 
      * entering the gateway portal.
+     * <p>
+     * If this block state is not placed the location's world will be null.
      * 
      * @return the gateway exit location
      */
@@ -18,6 +20,8 @@ public interface EndGateway extends BlockState {
     /**
      * Sets the exit location that entities are teleported to when
      * they enter the gateway portal.
+     * <p>
+     * If this block state is not placed the location's world has to be null.
      * 
      * @param location the new exit location
      * @throws IllegalArgumentException for differing worlds

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

@@ -1,6 +1,6 @@
 package org.bukkit.block;
 
 /**
- * Represents an ender chest.
+ * Represents a captured state of an ender chest.
  */
 public interface EnderChest extends BlockState { }

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

@@ -2,6 +2,9 @@ package org.bukkit.block;
 
 import org.bukkit.material.MaterialData;
 
+/**
+ * Represents a captured state of a flower pot.
+ */
 public interface FlowerPot extends BlockState {
 
     /**

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

@@ -2,12 +2,11 @@ package org.bukkit.block;
 
 import org.bukkit.Nameable;
 import org.bukkit.inventory.FurnaceInventory;
-import org.bukkit.inventory.InventoryHolder;
 
 /**
- * Represents a furnace.
+ * Represents a captured state of a furnace.
  */
-public interface Furnace extends BlockState, InventoryHolder, Lockable, Nameable {
+public interface Furnace extends Container, Nameable {
 
     /**
      * Get burn time.
@@ -37,5 +36,9 @@ public interface Furnace extends BlockState, InventoryHolder, Lockable, Nameable
      */
     public void setCookTime(short cookTime);
 
+    @Override
     public FurnaceInventory getInventory();
+
+    @Override
+    public FurnaceInventory getSnapshotInventory();
 }

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

@@ -1,9 +1,8 @@
 package org.bukkit.block;
 
 import org.bukkit.Nameable;
-import org.bukkit.inventory.InventoryHolder;
 
 /**
- * Represents a hopper.
+ * Represents a captured state of a hopper.
  */
-public interface Hopper extends BlockState, InventoryHolder, Lockable, Nameable { }
+public interface Hopper extends Container, Nameable { }

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

@@ -3,34 +3,39 @@ package org.bukkit.block;
 import org.bukkit.Material;
 
 /**
- * Represents a Jukebox
+ * Represents a captured state of a jukebox.
  */
 public interface Jukebox extends BlockState {
+
     /**
-     * Get the record currently playing
+     * Gets the record being played.
      *
      * @return The record Material, or AIR if none is playing
      */
     public Material getPlaying();
 
     /**
-     * Set the record currently playing
+     * Sets the record being played.
      *
      * @param record The record Material, or null/AIR to stop playing
      */
     public void setPlaying(Material record);
 
     /**
-     * Check if the jukebox is currently playing a record
+     * Checks if the jukebox is playing a record.
      *
      * @return True if there is a record playing
      */
     public boolean isPlaying();
 
     /**
-     * Stop the jukebox playing and eject the current record
+     * Stops the jukebox playing and ejects the current record.
+     * <p>
+     * If the block represented by this state is no longer a jukebox, this will
+     * do nothing and return false.
      *
      * @return True if a record was ejected; false if there was none playing
+     * @throws IllegalStateException if this block state is not placed
      */
     public boolean eject();
 }

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

@@ -4,7 +4,7 @@ import org.bukkit.Instrument;
 import org.bukkit.Note;
 
 /**
- * Represents a note.
+ * Represents a captured state of a note block.
  */
 public interface NoteBlock extends BlockState {
 
@@ -41,31 +41,41 @@ public interface NoteBlock extends BlockState {
     public void setRawNote(byte note);
 
     /**
-     * Attempts to play the note at block
+     * Attempts to play the note at the block.
      * <p>
-     * If the block is no longer a note block, this will return false
+     * If the block represented by this block state is no longer a note block,
+     * this will return false.
      *
      * @return true if successful, otherwise false
+     * @throws IllegalStateException if this block state is not placed
      */
     public boolean play();
 
     /**
-     * Plays an arbitrary note with an arbitrary instrument
+     * Plays an arbitrary note with an arbitrary instrument at the block.
+     * <p>
+     * If the block represented by this block state is no longer a note block,
+     * this will return false.
      *
      * @param instrument Instrument ID
      * @param note Note ID
      * @return true if successful, otherwise false
+     * @throws IllegalStateException if this block state is not placed
      * @deprecated Magic value
      */
     @Deprecated
     public boolean play(byte instrument, byte note);
 
     /**
-     * Plays an arbitrary note with an arbitrary instrument
+     * Plays an arbitrary note with an arbitrary instrument at the block.
+     * <p>
+     * If the block represented by this block state is no longer a note block,
+     * this will return false.
      *
      * @param instrument The instrument
      * @param note The note
      * @return true if successful, otherwise false
+     * @throws IllegalStateException if this block state is not placed
      * @see Instrument Note
      */
     public boolean play(Instrument instrument, Note note);

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

@@ -2,12 +2,11 @@ package org.bukkit.block;
 
 import org.bukkit.DyeColor;
 import org.bukkit.Nameable;
-import org.bukkit.inventory.InventoryHolder;
 
 /**
- * Represents a ShulkerBox.
+ * Represents a captured state of a ShulkerBox.
  */
-public interface ShulkerBox extends BlockState, InventoryHolder, Lockable, Nameable {
+public interface ShulkerBox extends Container, Nameable {
 
     /**
      * Get the {@link DyeColor} corresponding to this ShulkerBox

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

@@ -1,7 +1,7 @@
 package org.bukkit.block;
 
 /**
- * Represents either a SignPost or a WallSign
+ * Represents a captured state of either a SignPost or a WallSign.
  */
 public interface Sign extends BlockState {
 

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

@@ -1,11 +1,10 @@
 package org.bukkit.block;
 
-import java.util.UUID;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.SkullType;
 
 /**
- * Represents a Skull
+ * Represents a captured state of a skull block.
  */
 public interface Skull extends BlockState {
 

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

@@ -1,3 +1,6 @@
 package org.bukkit.block;
 
+/**
+ * Represents a captured state of structure block.
+ */
 public interface Structure extends BlockState {}