summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLukas Hennig <lukas@wirsindwir.de>2017-08-05 14:35:40 +1000
committermd_5 <git@md-5.net>2017-08-05 14:35:40 +1000
commitcadf99513061ffc795dd13d3afad81330716241a (patch)
tree358525f5bbc1bbd5667af4fe910a1c30691631ee
parent0aeac440c05a3ae3b69095e109372b7400f0feae (diff)
downloadbukkit-cadf99513061ffc795dd13d3afad81330716241a.tar
bukkit-cadf99513061ffc795dd13d3afad81330716241a.tar.gz
bukkit-cadf99513061ffc795dd13d3afad81330716241a.tar.lz
bukkit-cadf99513061ffc795dd13d3afad81330716241a.tar.xz
bukkit-cadf99513061ffc795dd13d3afad81330716241a.zip
Improvements to BlockStates
* Update Javadoc of block state classes to better match implementation behaviour. * Add Container interface which provides access to the snapshot inventory.
-rw-r--r--src/main/java/org/bukkit/block/Banner.java3
-rw-r--r--src/main/java/org/bukkit/block/Beacon.java16
-rw-r--r--src/main/java/org/bukkit/block/Bed.java2
-rw-r--r--src/main/java/org/bukkit/block/BlockState.java58
-rw-r--r--src/main/java/org/bukkit/block/BrewingStand.java13
-rw-r--r--src/main/java/org/bukkit/block/Chest.java19
-rw-r--r--src/main/java/org/bukkit/block/CommandBlock.java3
-rw-r--r--src/main/java/org/bukkit/block/Comparator.java2
-rw-r--r--src/main/java/org/bukkit/block/Container.java36
-rw-r--r--src/main/java/org/bukkit/block/CreatureSpawner.java2
-rw-r--r--src/main/java/org/bukkit/block/DaylightDetector.java2
-rw-r--r--src/main/java/org/bukkit/block/Dispenser.java17
-rw-r--r--src/main/java/org/bukkit/block/Dropper.java20
-rw-r--r--src/main/java/org/bukkit/block/EnchantingTable.java2
-rw-r--r--src/main/java/org/bukkit/block/EndGateway.java6
-rw-r--r--src/main/java/org/bukkit/block/EnderChest.java2
-rw-r--r--src/main/java/org/bukkit/block/FlowerPot.java3
-rw-r--r--src/main/java/org/bukkit/block/Furnace.java9
-rw-r--r--src/main/java/org/bukkit/block/Hopper.java5
-rw-r--r--src/main/java/org/bukkit/block/Jukebox.java15
-rw-r--r--src/main/java/org/bukkit/block/NoteBlock.java20
-rw-r--r--src/main/java/org/bukkit/block/ShulkerBox.java5
-rw-r--r--src/main/java/org/bukkit/block/Sign.java2
-rw-r--r--src/main/java/org/bukkit/block/Skull.java3
-rw-r--r--src/main/java/org/bukkit/block/Structure.java3
25 files changed, 186 insertions, 82 deletions
diff --git a/src/main/java/org/bukkit/block/Banner.java b/src/main/java/org/bukkit/block/Banner.java
index 723b8836..cabf4744 100644
--- a/src/main/java/org/bukkit/block/Banner.java
+++ b/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 {
/**
diff --git a/src/main/java/org/bukkit/block/Beacon.java b/src/main/java/org/bukkit/block/Beacon.java
index b1f97c9f..97d39213 100644
--- a/src/main/java/org/bukkit/block/Beacon.java
+++ b/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();
diff --git a/src/main/java/org/bukkit/block/Bed.java b/src/main/java/org/bukkit/block/Bed.java
index e93fa707..17a807a9 100644
--- a/src/main/java/org/bukkit/block/Bed.java
+++ b/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 { }
diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java
index 866a73d9..4b13d494 100644
--- a/src/main/java/org/bukkit/block/BlockState.java
+++ b/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
diff --git a/src/main/java/org/bukkit/block/BrewingStand.java b/src/main/java/org/bukkit/block/BrewingStand.java
index ea6ff4e1..f276c304 100644
--- a/src/main/java/org/bukkit/block/BrewingStand.java
+++ b/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();
}
diff --git a/src/main/java/org/bukkit/block/Chest.java b/src/main/java/org/bukkit/block/Chest.java
index ade09ddd..97dc7813 100644
--- a/src/main/java/org/bukkit/block/Chest.java
+++ b/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();
}
diff --git a/src/main/java/org/bukkit/block/CommandBlock.java b/src/main/java/org/bukkit/block/CommandBlock.java
index 85d53455..f94856cf 100644
--- a/src/main/java/org/bukkit/block/CommandBlock.java
+++ b/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 {
/**
diff --git a/src/main/java/org/bukkit/block/Comparator.java b/src/main/java/org/bukkit/block/Comparator.java
index dfb98c26..c9acc916 100644
--- a/src/main/java/org/bukkit/block/Comparator.java
+++ b/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 { }
diff --git a/src/main/java/org/bukkit/block/Container.java b/src/main/java/org/bukkit/block/Container.java
new file mode 100644
index 00000000..9eee5cc0
--- /dev/null
+++ b/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();
+}
diff --git a/src/main/java/org/bukkit/block/CreatureSpawner.java b/src/main/java/org/bukkit/block/CreatureSpawner.java
index a455bbcf..23a6dd86 100644
--- a/src/main/java/org/bukkit/block/CreatureSpawner.java
+++ b/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 {
diff --git a/src/main/java/org/bukkit/block/DaylightDetector.java b/src/main/java/org/bukkit/block/DaylightDetector.java
index 6457c339..ea4117ea 100644
--- a/src/main/java/org/bukkit/block/DaylightDetector.java
+++ b/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 { }
diff --git a/src/main/java/org/bukkit/block/Dispenser.java b/src/main/java/org/bukkit/block/Dispenser.java
index 39ee9b04..108332df 100644
--- a/src/main/java/org/bukkit/block/Dispenser.java
+++ b/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();
}
diff --git a/src/main/java/org/bukkit/block/Dropper.java b/src/main/java/org/bukkit/block/Dropper.java
index 0f1013bd..ba091374 100644
--- a/src/main/java/org/bukkit/block/Dropper.java
+++ b/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();
}
diff --git a/src/main/java/org/bukkit/block/EnchantingTable.java b/src/main/java/org/bukkit/block/EnchantingTable.java
index 64c9e650..9f5aa6c6 100644
--- a/src/main/java/org/bukkit/block/EnchantingTable.java
+++ b/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 { }
diff --git a/src/main/java/org/bukkit/block/EndGateway.java b/src/main/java/org/bukkit/block/EndGateway.java
index 3e77fd71..a1a6b3b0 100644
--- a/src/main/java/org/bukkit/block/EndGateway.java
+++ b/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
diff --git a/src/main/java/org/bukkit/block/EnderChest.java b/src/main/java/org/bukkit/block/EnderChest.java
index dfb808cb..e0eb2560 100644
--- a/src/main/java/org/bukkit/block/EnderChest.java
+++ b/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 { }
diff --git a/src/main/java/org/bukkit/block/FlowerPot.java b/src/main/java/org/bukkit/block/FlowerPot.java
index 3db6f804..5204717a 100644
--- a/src/main/java/org/bukkit/block/FlowerPot.java
+++ b/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 {
/**
diff --git a/src/main/java/org/bukkit/block/Furnace.java b/src/main/java/org/bukkit/block/Furnace.java
index b077eb37..ee8a9560 100644
--- a/src/main/java/org/bukkit/block/Furnace.java
+++ b/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();
}
diff --git a/src/main/java/org/bukkit/block/Hopper.java b/src/main/java/org/bukkit/block/Hopper.java
index 8e5e3e89..bc3aeef2 100644
--- a/src/main/java/org/bukkit/block/Hopper.java
+++ b/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 { }
diff --git a/src/main/java/org/bukkit/block/Jukebox.java b/src/main/java/org/bukkit/block/Jukebox.java
index 7b45b833..e070d874 100644
--- a/src/main/java/org/bukkit/block/Jukebox.java
+++ b/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();
}
diff --git a/src/main/java/org/bukkit/block/NoteBlock.java b/src/main/java/org/bukkit/block/NoteBlock.java
index 8380068f..2f9ac5c0 100644
--- a/src/main/java/org/bukkit/block/NoteBlock.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/block/ShulkerBox.java b/src/main/java/org/bukkit/block/ShulkerBox.java
index 003cfb8a..4c1740e7 100644
--- a/src/main/java/org/bukkit/block/ShulkerBox.java
+++ b/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
diff --git a/src/main/java/org/bukkit/block/Sign.java b/src/main/java/org/bukkit/block/Sign.java
index 5d7a633d..f30666a4 100644
--- a/src/main/java/org/bukkit/block/Sign.java
+++ b/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 {
diff --git a/src/main/java/org/bukkit/block/Skull.java b/src/main/java/org/bukkit/block/Skull.java
index 7fbbc6be..f69f9477 100644
--- a/src/main/java/org/bukkit/block/Skull.java
+++ b/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 {
diff --git a/src/main/java/org/bukkit/block/Structure.java b/src/main/java/org/bukkit/block/Structure.java
index dd5b8b1e..4cbfc7bb 100644
--- a/src/main/java/org/bukkit/block/Structure.java
+++ b/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 {}