diff --git a/paper-api/src/main/java/org/bukkit/block/Banner.java b/paper-api/src/main/java/org/bukkit/block/Banner.java index 723b88363c..cabf4744e5 100644 --- a/paper-api/src/main/java/org/bukkit/block/Banner.java +++ b/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 { /** diff --git a/paper-api/src/main/java/org/bukkit/block/Beacon.java b/paper-api/src/main/java/org/bukkit/block/Beacon.java index b1f97c9f8c..97d3921319 100644 --- a/paper-api/src/main/java/org/bukkit/block/Beacon.java +++ b/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. + *
+ * 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
+ * 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.
*
* If the provided Location is null this method does nothing and returns
* null.
+ *
+ * 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.
*
+ * If this state is not placed, this will have no effect and return true.
+ *
* 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
+ *
+ * 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/paper-api/src/main/java/org/bukkit/block/BrewingStand.java b/paper-api/src/main/java/org/bukkit/block/BrewingStand.java
index ea6ff4e105..f276c304f8 100644
--- a/paper-api/src/main/java/org/bukkit/block/BrewingStand.java
+++ b/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();
}
diff --git a/paper-api/src/main/java/org/bukkit/block/Chest.java b/paper-api/src/main/java/org/bukkit/block/Chest.java
index ade09dddbf..97dc7813fa 100644
--- a/paper-api/src/main/java/org/bukkit/block/Chest.java
+++ b/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.
+ *
+ * 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.
+ *
+ * If the block was changed to a different type in the meantime, the
+ * returned inventory might no longer be valid.
+ *
+ * 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/paper-api/src/main/java/org/bukkit/block/CommandBlock.java b/paper-api/src/main/java/org/bukkit/block/CommandBlock.java
index 85d53455a6..f94856cfec 100644
--- a/paper-api/src/main/java/org/bukkit/block/CommandBlock.java
+++ b/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 {
/**
diff --git a/paper-api/src/main/java/org/bukkit/block/Comparator.java b/paper-api/src/main/java/org/bukkit/block/Comparator.java
index dfb98c260f..c9acc916d9 100644
--- a/paper-api/src/main/java/org/bukkit/block/Comparator.java
+++ b/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 { }
diff --git a/paper-api/src/main/java/org/bukkit/block/Container.java b/paper-api/src/main/java/org/bukkit/block/Container.java
new file mode 100644
index 0000000000..9eee5cc0f3
--- /dev/null
+++ b/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.
+ *
+ * If the block was changed to a different type in the meantime, the
+ * returned inventory might no longer be valid.
+ *
+ * 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.
+ *
+ * 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/paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java b/paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java
index a455bbcf27..23a6dd869f 100644
--- a/paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java
+++ b/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 {
diff --git a/paper-api/src/main/java/org/bukkit/block/DaylightDetector.java b/paper-api/src/main/java/org/bukkit/block/DaylightDetector.java
index 6457c3396d..ea4117ea8d 100644
--- a/paper-api/src/main/java/org/bukkit/block/DaylightDetector.java
+++ b/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 { }
diff --git a/paper-api/src/main/java/org/bukkit/block/Dispenser.java b/paper-api/src/main/java/org/bukkit/block/Dispenser.java
index 39ee9b0462..108332dfb6 100644
--- a/paper-api/src/main/java/org/bukkit/block/Dispenser.java
+++ b/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.
*
- * 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.
*
- * 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/paper-api/src/main/java/org/bukkit/block/Dropper.java b/paper-api/src/main/java/org/bukkit/block/Dropper.java
index 0f1013bd15..ba0913749a 100644
--- a/paper-api/src/main/java/org/bukkit/block/Dropper.java
+++ b/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.
*
- * Normal behavior of a Dropper is as follows:
+ * Normal behavior of a dropper is as follows:
*
- * 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.
*
- * 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}.
+ *
+ * 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/paper-api/src/main/java/org/bukkit/block/EnchantingTable.java b/paper-api/src/main/java/org/bukkit/block/EnchantingTable.java
index 64c9e65048..9f5aa6c6c5 100644
--- a/paper-api/src/main/java/org/bukkit/block/EnchantingTable.java
+++ b/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 { }
diff --git a/paper-api/src/main/java/org/bukkit/block/EndGateway.java b/paper-api/src/main/java/org/bukkit/block/EndGateway.java
index 3e77fd717b..a1a6b3b010 100644
--- a/paper-api/src/main/java/org/bukkit/block/EndGateway.java
+++ b/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.
+ *
+ * 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.
+ *
+ * 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/paper-api/src/main/java/org/bukkit/block/EnderChest.java b/paper-api/src/main/java/org/bukkit/block/EnderChest.java
index dfb808cb72..e0eb2560ff 100644
--- a/paper-api/src/main/java/org/bukkit/block/EnderChest.java
+++ b/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 { }
diff --git a/paper-api/src/main/java/org/bukkit/block/FlowerPot.java b/paper-api/src/main/java/org/bukkit/block/FlowerPot.java
index 3db6f8047b..5204717a35 100644
--- a/paper-api/src/main/java/org/bukkit/block/FlowerPot.java
+++ b/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 {
/**
diff --git a/paper-api/src/main/java/org/bukkit/block/Furnace.java b/paper-api/src/main/java/org/bukkit/block/Furnace.java
index b077eb37f4..ee8a956019 100644
--- a/paper-api/src/main/java/org/bukkit/block/Furnace.java
+++ b/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();
}
diff --git a/paper-api/src/main/java/org/bukkit/block/Hopper.java b/paper-api/src/main/java/org/bukkit/block/Hopper.java
index 8e5e3e89dc..bc3aeef27a 100644
--- a/paper-api/src/main/java/org/bukkit/block/Hopper.java
+++ b/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 { }
diff --git a/paper-api/src/main/java/org/bukkit/block/Jukebox.java b/paper-api/src/main/java/org/bukkit/block/Jukebox.java
index 7b45b833dc..e070d87485 100644
--- a/paper-api/src/main/java/org/bukkit/block/Jukebox.java
+++ b/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.
+ *
+ * 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/paper-api/src/main/java/org/bukkit/block/NoteBlock.java b/paper-api/src/main/java/org/bukkit/block/NoteBlock.java
index 8380068f3c..2f9ac5c05c 100644
--- a/paper-api/src/main/java/org/bukkit/block/NoteBlock.java
+++ b/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.
*
- * 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.
+ *
+ * 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.
+ *
+ * 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/paper-api/src/main/java/org/bukkit/block/ShulkerBox.java b/paper-api/src/main/java/org/bukkit/block/ShulkerBox.java
index 003cfb8a1a..4c1740e703 100644
--- a/paper-api/src/main/java/org/bukkit/block/ShulkerBox.java
+++ b/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
diff --git a/paper-api/src/main/java/org/bukkit/block/Sign.java b/paper-api/src/main/java/org/bukkit/block/Sign.java
index 5d7a633dcb..f30666a421 100644
--- a/paper-api/src/main/java/org/bukkit/block/Sign.java
+++ b/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 {
diff --git a/paper-api/src/main/java/org/bukkit/block/Skull.java b/paper-api/src/main/java/org/bukkit/block/Skull.java
index 7fbbc6be8c..f69f94773d 100644
--- a/paper-api/src/main/java/org/bukkit/block/Skull.java
+++ b/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 {
diff --git a/paper-api/src/main/java/org/bukkit/block/Structure.java b/paper-api/src/main/java/org/bukkit/block/Structure.java
index dd5b8b1e76..4cbfc7bb2c 100644
--- a/paper-api/src/main/java/org/bukkit/block/Structure.java
+++ b/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 {}