Make a start on BlockState stuff

3 files changed, 126 insertions, 4 deletions

diff --git a/src/main/java/org/bukkit/Block.java b/src/main/java/org/bukkit/Block.java
index 63cabda8..d2719be2 100644
--- a/src/main/java/org/bukkit/Block.java
+++ b/src/main/java/org/bukkit/Block.java
@@ -1,7 +1,12 @@
 package org.bukkit;
 
+import org.bukkit.block.BlockState;
+
 /**
- * Represents a block
+ * Represents a block. This is a live object, and only one Block may exist for
+ * any given location in a world. The state of the block may change concurrently
+ * to your own handling of it; use block.getState() to get a snapshot state of a
+ * block which will not be modified.
  */
 public interface Block {
     /**
@@ -143,4 +148,15 @@ public interface Block {
      * @return BlockFace of this block which has the requested block, or null
      */
     BlockFace getFace(Block block);
+
+    /**
+     * Captures the current state of this block. You may then cast that state
+     * into any accepted type, such as Furnace or Sign.
+     *
+     * The returned object will never be updated, and you are not guaranteed that
+     * (for example) a sign is still a sign after you capture its state.
+     *
+     * @return BlockState with the current state of this block.
+     */
+    BlockState getState();
 }
diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java
new file mode 100644
index 00000000..6b8c6161
--- /dev/null
+++ b/src/main/java/org/bukkit/block/BlockState.java
@@ -0,0 +1,108 @@
+
+package org.bukkit.block;
+
+import org.bukkit.Block;
+import org.bukkit.Chunk;
+import org.bukkit.Material;
+import org.bukkit.World;
+
+/**
+ * Represents a captured state of a block, which will not change automatically.
+ *
+ * Unlike Block, which only one object can exist per coordinate, BlockState can
+ * exist multiple times for any given Block. Note that another plugin may change
+ * the state of the block and you will not know, or they may change the block to
+ * another type entirely, causing your BlockState to become invalid.
+ */
+public interface BlockState {
+    /**
+     * Gets the block represented by this BlockState
+     * 
+     * @return Block that this BlockState represents
+     */
+    Block getBlock();
+
+    /**
+     * Gets the metadata for this block
+     *
+     * @return block specific metadata
+     */
+    byte getData();
+
+    /**
+     * Gets the type of this block
+     *
+     * @return block type
+     */
+    Material getType();
+
+    /**
+     * Gets the type-ID of this block
+     *
+     * @return block type-ID
+     */
+    int getTypeID();
+
+    /**
+     * Gets the light level between 0-15
+     *
+     * @return light level
+     */
+    byte getLightLevel();
+
+    /**
+     * Gets the world which contains this Block
+     *
+     * @return World containing this block
+     */
+    World getWorld();
+
+    /**
+     * Gets the x-coordinate of this block
+     *
+     * @return x-coordinate
+     */
+    int getX();
+
+    /**
+     * Gets the y-coordinate of this block
+     *
+     * @return y-coordinate
+     */
+    int getY();
+
+    /**
+     * Gets the z-coordinate of this block
+     *
+     * @return z-coordinate
+     */
+    int getZ();
+
+    /**
+     * Gets the chunk which contains this block
+     *
+     * @return Containing Chunk
+     */
+    Chunk getChunk();
+
+    /**
+     * Sets the metadata for this block
+     *
+     * @param data New block specific metadata
+     */
+    void setData(byte data);
+
+    /**
+     * Sets the type of this block
+     *
+     * @param type Material to change this block to
+     */
+    void setType(Material type);
+
+    /**
+     * Sets the type-ID of this block
+     *
+     * @param type Type-ID to change this block to
+     */
+    void setTypeID(int type);
+}
diff --git a/src/main/java/org/bukkit/block/Sign.java b/src/main/java/org/bukkit/block/Sign.java
index 595c7836..8731f6c2 100644
--- a/src/main/java/org/bukkit/block/Sign.java
+++ b/src/main/java/org/bukkit/block/Sign.java
@@ -1,12 +1,10 @@
 
 package org.bukkit.block;
 
-import org.bukkit.Block;
-
 /**
  * Represents either a SignPost or a WallSign
  */
-public interface Sign extends Block {
+public interface Sign extends BlockState {
     /**
      * Gets all the lines of text currently on this sign.
      *