Add API for ItemFrames. Adds BUKKIT-2668

As well as adding methods for ItemFrames, this moves some methods
previously contained in Painting to Hanging, as they are shared by both
classes.

An enum was added that represents rotations, similar to a clock-face.
This is needed as a contrast to cardinal direction based rotations.

4 files changed, 95 insertions, 15 deletions

diff --git a/src/main/java/org/bukkit/Rotation.java b/src/main/java/org/bukkit/Rotation.java
new file mode 100644
index 00000000..02447745
--- /dev/null
+++ b/src/main/java/org/bukkit/Rotation.java
@@ -0,0 +1,45 @@
+package org.bukkit;
+
+/**
+ * An enum to specify a rotation based orientation, like that on a clock.
+ * It represents how something is viewed, as opposed to cardinal directions.
+ */
+public enum Rotation {
+    /**
+     * No rotation
+     */
+    NONE,
+    /**
+     * Rotated clockwise by 90 degrees
+     */
+    CLOCKWISE,
+    /**
+     * Flipped upside-down, a 180 degree rotation
+     */
+    FLIPPED,
+    /**
+     * Rotated counter-clockwise by 90 degrees
+     */
+    COUNTER_CLOCKWISE,
+    ;
+
+    private static final Rotation [] rotations = values();
+
+    /**
+     * Rotate clockwise by 90 degrees.
+     *
+     * @return the relative rotation
+     */
+    public Rotation rotateClockwise() {
+        return rotations[(this.ordinal() + 1) & 0x3];
+    }
+
+    /**
+     * Rotate counter-clockwise by 90 degrees.
+     *
+     * @return the relative rotation
+     */
+    public Rotation rotateCounterClockwise() {
+        return rotations[(this.ordinal() - 1) & 0x3];
+    }
+}
diff --git a/src/main/java/org/bukkit/entity/Hanging.java b/src/main/java/org/bukkit/entity/Hanging.java
index 46548ec0..0b1979d9 100644
--- a/src/main/java/org/bukkit/entity/Hanging.java
+++ b/src/main/java/org/bukkit/entity/Hanging.java
@@ -1,6 +1,20 @@
 package org.bukkit.entity;
 
+import org.bukkit.block.BlockFace;
+import org.bukkit.material.Attachable;
+
 /**
  * Represents a Hanging entity
  */
-public interface Hanging extends Entity {}
+public interface Hanging extends Entity, Attachable {
+
+    /**
+     * Sets the direction of the hanging entity, potentially overriding rules of placement. Note that if the result
+     * is not valid the object would normally drop as an item.
+     *
+     * @param face The new direction.
+     * @param force Whether to force it.
+     * @return False if force was false and there was no block for it to attach to in order to face the given direction.
+     */
+    public boolean setFacingDirection(BlockFace face, boolean force);
+}
diff --git a/src/main/java/org/bukkit/entity/ItemFrame.java b/src/main/java/org/bukkit/entity/ItemFrame.java
index 769cfd2f..8b86815d 100644
--- a/src/main/java/org/bukkit/entity/ItemFrame.java
+++ b/src/main/java/org/bukkit/entity/ItemFrame.java
@@ -1,6 +1,39 @@
 package org.bukkit.entity;
 
+import org.bukkit.Rotation;
+import org.bukkit.inventory.ItemStack;
+
 /**
  * Represents an Item Frame
  */
-public interface ItemFrame extends Hanging {}
+public interface ItemFrame extends Hanging {
+
+    /**
+     * Get the item in this frame
+     *
+     * @return a defensive copy the item in this item frame
+     */
+    public ItemStack getItem();
+
+    /**
+     * Set the item in this frame
+     *
+     * @param item the new item
+     */
+    public void setItem(ItemStack item);
+
+    /**
+     * Get the rotation of the frame's item
+     *
+     * @return the direction
+     */
+    public Rotation getRotation();
+
+    /**
+     * Set the rotation of the frame's item
+     *
+     * @param rotation the new rotation
+     * @throws IllegalArgumentException if rotation is null
+     */
+    public void setRotation(Rotation rotation) throws IllegalArgumentException;
+}
diff --git a/src/main/java/org/bukkit/entity/Painting.java b/src/main/java/org/bukkit/entity/Painting.java
index ddc84524..3326a9fe 100644
--- a/src/main/java/org/bukkit/entity/Painting.java
+++ b/src/main/java/org/bukkit/entity/Painting.java
@@ -1,14 +1,12 @@
 package org.bukkit.entity;
 
 import org.bukkit.Art;
-import org.bukkit.block.BlockFace;
 import org.bukkit.event.painting.PaintingBreakEvent;
-import org.bukkit.material.Attachable;
 
 /**
  * Represents a Painting.
  */
-public interface Painting extends Entity, Attachable {
+public interface Painting extends Hanging {
     /**
      * Get the art on this painting
      *
@@ -34,14 +32,4 @@ public interface Painting extends Entity, Attachable {
      * @return False if force was false and the new art won't fit at the painting's current location
      */
     public boolean setArt(Art art, boolean force);
-
-    /**
-     * Sets the direction of the painting, potentially overriding rules of placement. Note that if the result
-     * is not valid the painting would normally drop as an item.
-     *
-     * @param face The new direction.
-     * @param force Whether to force it.
-     * @return False if force was false and there was no block for it to attach to in order to face the given direction.
-     */
-    public boolean setFacingDirection(BlockFace face, boolean force);
 }