[Bleeding] Add ProjectileSource interface. Addresses BUKKIT-1038, BUKKIT-1156

6 files changed, 86 insertions, 20 deletions

diff --git a/src/main/java/org/bukkit/block/Dispenser.java b/src/main/java/org/bukkit/block/Dispenser.java
index 70917947..bba753ee 100644
--- a/src/main/java/org/bukkit/block/Dispenser.java
+++ b/src/main/java/org/bukkit/block/Dispenser.java
@@ -1,14 +1,25 @@
 package org.bukkit.block;
 
+import org.bukkit.projectiles.BlockProjectileSource;
+
 /**
  * Represents a dispenser.
  */
 public interface Dispenser extends BlockState, ContainerBlock {
 
     /**
-     * Attempts to dispense the contents of this block
+     * Gets the BlockProjectileSource object for this dispenser.
+     * <p>
+     * If the block is no longer a dispenser, this will return null.
+     *
+     * @return a BlockProjectileSource if valid, otherwise null
+     */
+    public BlockProjectileSource getBlockProjectileSource();
+
+    /**
+     * Attempts to dispense the contents of this block.
      * <p>
-     * If the block is no longer a dispenser, this will return false
+     * If the block is no longer a dispenser, this will return false.
      *
      * @return true if successful, otherwise false
      */
diff --git a/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java
index 89926b29..6c8b4f86 100644
--- a/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/src/main/java/org/bukkit/entity/LivingEntity.java
@@ -9,11 +9,12 @@ import org.bukkit.block.Block;
 import org.bukkit.inventory.EntityEquipment;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
+import org.bukkit.projectiles.ProjectileSource;
 
 /**
  * Represents a living entity, such as a monster or player
  */
-public interface LivingEntity extends Entity, Damageable {
+public interface LivingEntity extends Entity, Damageable, ProjectileSource {
 
     /**
      * Gets the height of the living entity's eyes above its Location.
@@ -112,14 +113,6 @@ public interface LivingEntity extends Entity, Damageable {
     public Arrow shootArrow();
 
     /**
-     * Launches a {@link Projectile} from the living entity.
-     *
-     * @param projectile class of the projectile to launch
-     * @return the launched projectile
-     */
-    public <T extends Projectile> T launchProjectile(Class<? extends T> projectile);
-
-    /**
      * Returns the amount of air that the living entity has remaining, in
      * ticks.
      *
diff --git a/src/main/java/org/bukkit/entity/Projectile.java b/src/main/java/org/bukkit/entity/Projectile.java
index 9d5e92d3..02c840c3 100644
--- a/src/main/java/org/bukkit/entity/Projectile.java
+++ b/src/main/java/org/bukkit/entity/Projectile.java
@@ -1,26 +1,41 @@
 package org.bukkit.entity;
 
-import org.bukkit.block.Dispenser;
+import org.bukkit.projectiles.ProjectileSource;
 
 /**
- * Represents a shootable entity
+ * Represents a shootable entity.
  */
 public interface Projectile extends Entity {
 
     /**
-     * Retrieve the shooter of this projectile. The returned value can be null
-     * for projectiles shot from a {@link Dispenser} for example.
+     * This method exists for legacy reasons to provide backwards
+     * compatibility. It will not exist at runtime and should not be used
+     * under any circumstances.
+     */
+    @Deprecated
+    public LivingEntity _INVALID_getShooter();
+
+    /**
+     * Retrieve the shooter of this projectile.
      *
-     * @return the {@link LivingEntity} that shot this projectile
+     * @return the {@link ProjectileSource} that shot this projectile
+     */
+    public ProjectileSource getShooter();
+
+    /**
+     * This method exists for legacy reasons to provide backwards
+     * compatibility. It will not exist at runtime and should not be used
+     * under any circumstances.
      */
-    public LivingEntity getShooter();
+    @Deprecated
+    public void _INVALID_setShooter(LivingEntity shooter);
 
     /**
-     * Set the shooter of this projectile
+     * Set the shooter of this projectile.
      *
-     * @param shooter the {@link LivingEntity} that shot this projectile
+     * @param shooter the {@link ProjectileSource} that shot this projectile
      */
-    public void setShooter(LivingEntity shooter);
+    public void setShooter(ProjectileSource source);
 
     /**
      * Determine if this projectile should bounce or not when it hits.
diff --git a/src/main/java/org/bukkit/projectiles/BlockProjectileSource.java b/src/main/java/org/bukkit/projectiles/BlockProjectileSource.java
new file mode 100644
index 00000000..e713c0d8
--- /dev/null
+++ b/src/main/java/org/bukkit/projectiles/BlockProjectileSource.java
@@ -0,0 +1,13 @@
+package org.bukkit.projectiles;
+
+import org.bukkit.block.Block;
+
+public interface BlockProjectileSource extends ProjectileSource {
+
+    /**
+     * Gets the block this projectile source belongs to.
+     *
+     * @return Block for the projectile source
+     */
+    public Block getBlock();
+}
diff --git a/src/main/java/org/bukkit/projectiles/ProjectileSource.java b/src/main/java/org/bukkit/projectiles/ProjectileSource.java
new file mode 100644
index 00000000..afad8d74
--- /dev/null
+++ b/src/main/java/org/bukkit/projectiles/ProjectileSource.java
@@ -0,0 +1,28 @@
+package org.bukkit.projectiles;
+
+import org.bukkit.entity.Projectile;
+import org.bukkit.util.Vector;
+
+/**
+ * Represents a valid source of a projectile.
+ */
+public interface ProjectileSource {
+
+    /**
+     * Launches a {@link Projectile} from the ProjectileSource.
+     *
+     * @param projectile class of the projectile to launch
+     * @return the launched projectile
+     */
+    public <T extends Projectile> T launchProjectile(Class<? extends T> projectile);
+
+    /**
+     * Launches a {@link Projectile} from the ProjectileSource with an
+     * initial velocity.
+     *
+     * @param projectile class of the projectile to launch
+     * @param velocity the velocity with which to launch
+     * @return the launched projectile
+     */
+    public <T extends Projectile> T launchProjectile(Class<? extends T> projectile, Vector velocity);
+}
diff --git a/src/main/javadoc/org/bukkit/projectiles/package-info.java b/src/main/javadoc/org/bukkit/projectiles/package-info.java
new file mode 100644
index 00000000..0e396627
--- /dev/null
+++ b/src/main/javadoc/org/bukkit/projectiles/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes to represent the source of a projectile
+ * <p>
+ */
+package org.bukkit.projectiles;
+