Update JavaDocs regarding teleportation of entities. Fixes BUKKIT-4210

Up until Minecraft version 1.5 it was not possible to teleport entities
within vehicles. With the 1.5 update came the change in the Minecraft
teleportation logic to dismount before teleporting the entity, if
applicable.

This commit simply ammends the JavaDocs for the associated CraftBukkit
half regarding the action the teleportation methods will take before
completing a teleport.

pom.xml

@@ -2,7 +2,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.bukkit</groupId>
     <artifactId>bukkit</artifactId>
-    <version>1.7.9-R0.3-SNAPSHOT</version>
+    <version>1.7.10-R0.1-SNAPSHOT</version>
     <name>Bukkit</name>
     <url>http://www.bukkit.org</url>
 

src/main/java/org/bukkit/Bukkit.java

@@ -2,6 +2,7 @@ package org.bukkit;
 
 import java.awt.image.BufferedImage;
 import java.io.File;
+import java.util.Collection;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
@@ -89,10 +90,23 @@ public final class Bukkit {
         return server.getBukkitVersion();
     }
 
+    /**
+     * 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
+     * @see Server#_INVALID_getOnlinePlayers()
+     */
+    @Deprecated
+    public static Player[] _INVALID_getOnlinePlayers() {
+        return server._INVALID_getOnlinePlayers();
+    }
+
     /**
      * @see Server#getOnlinePlayers()
      */
-    public static Player[] getOnlinePlayers() {
+    public static Collection<? extends Player> getOnlinePlayers() {
         return server.getOnlinePlayers();
     }
 

src/main/java/org/bukkit/GameMode.java

@@ -23,7 +23,7 @@ public enum GameMode {
     SURVIVAL(0),
 
     /**
-     * Adventure mode cannot break blocks, use chat, use buckets, etc.
+     * Adventure mode cannot break blocks without the correct tools.
      */
     ADVENTURE(2);
 

src/main/java/org/bukkit/Location.java

@@ -219,7 +219,7 @@ public class Location implements Cloneable {
     }
 
     /**
-     * Sets the pitch of this location, measured in degrees.
+     * Gets the pitch of this location, measured in degrees.
      * <ul>
      * <li>A pitch of 0 represents level forward facing.
      * <li>A pitch of 90 represents downward facing, or negative y

src/main/java/org/bukkit/Server.java

@@ -2,6 +2,9 @@ package org.bukkit;
 
 import java.awt.image.BufferedImage;
 import java.io.File;
+import java.io.Serializable;
+import java.util.Collection;
+import java.util.Collections;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
@@ -14,6 +17,7 @@ import org.bukkit.command.CommandException;
 import org.bukkit.command.CommandSender;
 import org.bukkit.command.ConsoleCommandSender;
 import org.bukkit.command.PluginCommand;
+import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.event.inventory.InventoryType;
 import org.bukkit.event.server.ServerListPingEvent;
@@ -33,6 +37,7 @@ import org.bukkit.scoreboard.ScoreboardManager;
 import org.bukkit.util.CachedServerIcon;
 
 import com.avaje.ebean.config.ServerConfig;
+import com.google.common.collect.ImmutableList;
 
 import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.meta.ItemMeta;
@@ -80,11 +85,46 @@ public interface Server extends PluginMessageRecipient {
     public String getBukkitVersion();
 
     /**
-     * Gets a list of all currently logged in players.
+     * Gets an array copy of all currently logged in players.
+     * <p>
+     * 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 superseded by {@link #getOnlinePlayers()}
      * @return an array of Players that are currently online
      */
-    public Player[] getOnlinePlayers();
+    @Deprecated
+    public Player[] _INVALID_getOnlinePlayers();
+
+    /**
+     * Gets a view of all currently logged in players. This {@linkplain
+     * Collections#unmodifiableCollection(Collection) view} is a reused
+     * object, making some operations like {@link Collection#size()}
+     * zero-allocation.
+     * <p>
+     * The collection is a view backed by the internal representation, such
+     * that, changes to the internal state of the server will be reflected
+     * immediately. However, the reuse of the returned collection (identity)
+     * is not strictly guaranteed for future or all implementations. Casting
+     * the collection, or relying on interface implementations (like {@link
+     * Serializable} or {@link List}), is deprecated.
+     * <p>
+     * Iteration behavior is undefined outside of self-contained main-thread
+     * uses. Normal and immediate iterator use without consequences that
+     * affect the collection are fully supported. The effects following
+     * (non-exhaustive) {@link Entity#teleport(Location) teleportation},
+     * {@link Player#setHealth(double) death}, and {@link Player#kickPlayer(
+     * String) kicking} are undefined. Any use of this collection from
+     * asynchronous threads is unsafe.
+     * <p>
+     * For safe consequential iteration or mimicking the old array behavior,
+     * using {@link Collection#toArray(Object[])} is recommended. For making
+     * snapshots, {@link ImmutableList#copyOf(Collection)} is recommended.
+     *
+     * @return a view of currently online players.
+     */
+    public Collection<? extends Player> getOnlinePlayers();
 
     /**
      * Get the maximum amount of players which can login to this server.

src/main/java/org/bukkit/command/defaults/DeopCommand.java

@@ -49,9 +49,9 @@ public class DeopCommand extends VanillaCommand {
 
         if (args.length == 1) {
             List<String> completions = new ArrayList<String>();
-            for (OfflinePlayer player : Bukkit.getOfflinePlayers()) {
+            for (OfflinePlayer player : Bukkit.getOperators()) {
                 String playerName = player.getName();
-                if (player.isOp() && StringUtil.startsWithIgnoreCase(playerName, args[0])) {
+                if (StringUtil.startsWithIgnoreCase(playerName, args[0])) {
                     completions.add(playerName);
                 }
             }

src/main/java/org/bukkit/command/defaults/ListCommand.java

@@ -1,5 +1,6 @@
 package org.bukkit.command.defaults;
 
+import java.util.Collection;
 import java.util.List;
 
 import org.apache.commons.lang.Validate;
@@ -23,7 +24,7 @@ public class ListCommand extends VanillaCommand {
 
         StringBuilder online = new StringBuilder();
 
-        Player[] players = Bukkit.getOnlinePlayers();
+        final Collection<? extends Player> players = Bukkit.getOnlinePlayers();
 
         for (Player player : players) {
             // If a player is hidden from the sender don't show them in the list
@@ -37,7 +38,7 @@ public class ListCommand extends VanillaCommand {
             online.append(player.getDisplayName());
         }
 
-        sender.sendMessage("There are " + players.length + "/" + Bukkit.getMaxPlayers() + " players online:\n" + online.toString());
+        sender.sendMessage("There are " + players.size() + "/" + Bukkit.getMaxPlayers() + " players online:\n" + online.toString());
 
         return true;
     }

src/main/java/org/bukkit/entity/Entity.java

@@ -65,7 +65,8 @@ public interface Entity extends Metadatable {
     public World getWorld();
 
     /**
-     * Teleports this entity to the given location
+     * Teleports this entity to the given location. If this entity is riding a
+     * vehicle, it will be dismounted prior to teleportation.
      *
      * @param location New location to teleport this entity to
      * @return <code>true</code> if the teleport was successful
@@ -73,7 +74,8 @@ public interface Entity extends Metadatable {
     public boolean teleport(Location location);
 
     /**
-     * Teleports this entity to the given location
+     * Teleports this entity to the given location. If this entity is riding a
+     * vehicle, it will be dismounted prior to teleportation.
      *
      * @param location New location to teleport this entity to
      * @param cause The cause of this teleportation
@@ -82,7 +84,8 @@ public interface Entity extends Metadatable {
     public boolean teleport(Location location, TeleportCause cause);
 
     /**
-     * Teleports this entity to the target Entity
+     * Teleports this entity to the target Entity. If this entity is riding a
+     * vehicle, it will be dismounted prior to teleportation.
      *
      * @param destination Entity to teleport this entity to
      * @return <code>true</code> if the teleport was successful
@@ -90,7 +93,8 @@ public interface Entity extends Metadatable {
     public boolean teleport(Entity destination);
 
     /**
-     * Teleports this entity to the target Entity
+     * Teleports this entity to the target Entity. If this entity is riding a
+     * vehicle, it will be dismounted prior to teleportation.
      *
      * @param destination Entity to teleport this entity to
      * @param cause The cause of this teleportation

src/main/java/org/bukkit/entity/Fish.java

@@ -2,28 +2,7 @@ package org.bukkit.entity;
 
 /**
  * Represents a fishing hook.
+ * @deprecated in favor of {@link FishHook}
  */
-public interface Fish extends Projectile {
+public interface Fish extends FishHook {
-
-    /**
-     * Gets the chance of a fish biting.
-     * <p>
-     * 0.0 = No Chance.<br>
-     * 1.0 = Instant catch.
-     *
-     * @return chance the bite chance
-     */
-    public double getBiteChance();
-
-    /**
-     * Sets the chance of a fish biting.
-     * <p>
-     * 0.0 = No Chance.<br>
-     * 1.0 = Instant catch.
-     *
-     * @param chance the bite chance
-     * @throws IllegalArgumentException if the bite chance is not between 0
-     *     and 1
-     */
-    public void setBiteChance(double chance) throws IllegalArgumentException;
 }

src/main/java/org/bukkit/entity/FishHook.java

@@ -0,0 +1,28 @@
+package org.bukkit.entity;
+
+/**
+ * Represents a fishing hook.
+ */
+public interface FishHook extends Projectile {
+    /**
+     * Gets the chance of a fish biting.
+     * <p>
+     * 0.0 = No Chance.<br>
+     * 1.0 = Instant catch.
+     *
+     * @return chance the bite chance
+     */
+    public double getBiteChance();
+
+    /**
+     * Sets the chance of a fish biting.
+     * <p>
+     * 0.0 = No Chance.<br>
+     * 1.0 = Instant catch.
+     *
+     * @param chance the bite chance
+     * @throws IllegalArgumentException if the bite chance is not between 0
+     *     and 1
+     */
+    public void setBiteChance(double chance) throws IllegalArgumentException;
+}

src/main/java/org/bukkit/entity/HumanEntity.java

@@ -148,14 +148,14 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
     public int getSleepTicks();
 
     /**
-     * Gets this humans current {@link GameMode}
+     * Gets this human's current {@link GameMode}
      *
      * @return Current game mode
      */
     public GameMode getGameMode();
 
     /**
-     * Sets this humans current {@link GameMode}
+     * Sets this human's current {@link GameMode}
      *
      * @param mode New game mode
      */

src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java

@@ -1,5 +1,8 @@
 package org.bukkit.event.entity;
 
+import java.util.Map;
+
+import com.google.common.base.Function;
 import org.bukkit.block.Block;
 import org.bukkit.entity.Entity;
 
@@ -14,11 +17,17 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent {
         this(damager, damagee, cause, (double) damage);
     }
 
+    @Deprecated
     public EntityDamageByBlockEvent(final Block damager, final Entity damagee, final DamageCause cause, final double damage) {
         super(damagee, cause, damage);
         this.damager = damager;
     }
 
+    public EntityDamageByBlockEvent(final Block damager, final Entity damagee, final DamageCause cause, final Map<DamageModifier, Double> modifiers, final Map<DamageModifier, ? extends Function<? super Double, Double>> modifierFunctions) {
+        super(damagee, cause, modifiers, modifierFunctions);
+        this.damager = damager;
+    }
+
     /**
      * Returns the block that damaged the player.
      *

src/main/java/org/bukkit/event/entity/EntityDamageByEntityEvent.java

@@ -1,5 +1,8 @@
 package org.bukkit.event.entity;
 
+import java.util.Map;
+
+import com.google.common.base.Function;
 import org.bukkit.entity.Entity;
 
 /**
@@ -13,11 +16,17 @@ public class EntityDamageByEntityEvent extends EntityDamageEvent {
         this(damager, damagee, cause, (double) damage);
     }
 
+    @Deprecated
     public EntityDamageByEntityEvent(final Entity damager, final Entity damagee, final DamageCause cause, final double damage) {
         super(damagee, cause, damage);
         this.damager = damager;
     }
 
+    public EntityDamageByEntityEvent(final Entity damager, final Entity damagee, final DamageCause cause, final Map<DamageModifier, Double> modifiers, final Map<DamageModifier, ? extends Function<? super Double, Double>> modifierFunctions) {
+        super(damagee, cause, modifiers, modifierFunctions);
+        this.damager = damager;
+    }
+
     /**
      * Returns the entity that damaged the defender.
      *

src/main/java/org/bukkit/event/entity/EntityDamageEvent.java

@@ -1,16 +1,29 @@
 package org.bukkit.event.entity;
 
+import java.util.EnumMap;
+import java.util.Map;
+
+import org.apache.commons.lang.Validate;
 import org.bukkit.entity.Entity;
+import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.util.NumberConversions;
 
+import com.google.common.base.Function;
+import com.google.common.base.Functions;
+import com.google.common.collect.ImmutableMap;
+
 /**
  * Stores data for damage events
  */
 public class EntityDamageEvent extends EntityEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
-    private double damage;
+    private static final DamageModifier[] MODIFIERS = DamageModifier.values();
+    private static final Function<? super Double, Double> ZERO = Functions.constant(-0.0);
+    private final Map<DamageModifier, Double> modifiers;
+    private final Map<DamageModifier, ? extends Function<? super Double, Double>> modifierFunctions;
+    private final Map<DamageModifier, Double> originals;
     private boolean cancelled;
     private final DamageCause cause;
 
@@ -19,10 +32,22 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
         this(damagee, cause, (double) damage);
     }
 
+    @Deprecated
     public EntityDamageEvent(final Entity damagee, final DamageCause cause, final double damage) {
+        this(damagee, cause, new EnumMap<DamageModifier, Double>(ImmutableMap.of(DamageModifier.BASE, damage)), new EnumMap<DamageModifier, Function<? super Double, Double>>(ImmutableMap.of(DamageModifier.BASE, ZERO)));
+    }
+
+    public EntityDamageEvent(final Entity damagee, final DamageCause cause, final Map<DamageModifier, Double> modifiers, final Map<DamageModifier, ? extends Function<? super Double, Double>> modifierFunctions) {
         super(damagee);
+        Validate.isTrue(modifiers.containsKey(DamageModifier.BASE), "BASE DamageModifier missing");
+        Validate.isTrue(!modifiers.containsKey(null), "Cannot have null DamageModifier");
+        Validate.noNullElements(modifiers.values(), "Cannot have null modifier values");
+        Validate.isTrue(modifiers.keySet().equals(modifierFunctions.keySet()), "Must have a modifier function for each DamageModifier");
+        Validate.noNullElements(modifierFunctions.values(), "Cannot have null modifier function");
+        this.originals = new EnumMap<DamageModifier, Double>(modifiers);
         this.cause = cause;
-        this.damage = damage;
+        this.modifiers = modifiers;
+        this.modifierFunctions = modifierFunctions;
     }
 
     public boolean isCancelled() {
@@ -34,11 +59,90 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
     }
 
     /**
-     * Gets the amount of damage caused by the event
+     * Gets the original damage for the specified modifier, as defined at this
+     * event's construction.
      *
-     * @return The amount of damage caused by the event
+     * @param type the modifier
+     * @throws IllegalArgumentException if type is null
+     */
+    public double getOriginalDamage(DamageModifier type) throws IllegalArgumentException {
+        final Double damage = originals.get(type);
+        if (damage != null) {
+            return damage;
+        }
+        if (type == null) {
+            throw new IllegalArgumentException("Cannot have null DamageModifier");
+        }
+        return 0;
+    }
+
+    /**
+     * Sets the damage for the specified modifier.
+     *
+     * @param damage the scalar value of the damage's modifier
+     * @see #getFinalDamage()
+     * @throws IllegalArgumentException if type is null
+     * @throws UnsupportedOperationException if the caller does not support
+     *     the particular DamageModifier, or to rephrase, when {@link
+     *     #isApplicable(DamageModifier)} returns false
+     */
+    public void setDamage(DamageModifier type, double damage) throws IllegalArgumentException, UnsupportedOperationException {
+        if (!modifiers.containsKey(type)) {
+            throw type == null ? new IllegalArgumentException("Cannot have null DamageModifier") : new UnsupportedOperationException(type + " is not applicable to " + getEntity());
+        }
+        modifiers.put(type, damage);
+    }
+
+    /**
+     * Gets the damage change for some modifier
+     *
+     * @return The raw amount of damage caused by the event
+     * @throws IllegalArgumentException if type is null
+     * @see DamageModifier#BASE
+     */
+    public double getDamage(DamageModifier type) throws IllegalArgumentException {
+        Validate.notNull(type, "Cannot have null DamageModifier");
+        final Double damage = modifiers.get(type);
+        return damage == null ? 0 : damage;
+    }
+
+    /**
+     * This checks to see if a particular modifier is valid for this event's
+     * caller, such that, {@link #setDamage(DamageModifier, double)} will not
+     * throw an {@link UnsupportedOperationException}.
+     * <p>
+     * {@link DamageModifier#BASE} is always applicable.
+     *
+     * @param type the modifier
+     * @return true if the modifier is supported by the caller, false otherwise
+     * @throws IllegalArgumentException if type is null
+     */
+    public boolean isApplicable(DamageModifier type) throws IllegalArgumentException {
+        Validate.notNull(type, "Cannot have null DamageModifier");
+        return modifiers.containsKey(type);
+    }
+
+    /**
+     * Gets the raw amount of damage caused by the event
+     *
+     * @return The raw amount of damage caused by the event
+     * @see DamageModifier#BASE
      */
     public double getDamage() {
+        return getDamage(DamageModifier.BASE);
+    }
+
+    /**
+     * Gets the amount of damage caused by the event after all damage
+     * reduction is applied.
+     *
+     * @return the amount of damage caused by the event
+     */
+    public final double getFinalDamage() {
+        double damage = 0;
+        for (DamageModifier modifier : MODIFIERS) {
+            damage += getDamage(modifier);
+        }
         return damage;
     }
 
@@ -53,12 +157,40 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
     }
 
     /**
-     * Sets the amount of damage caused by the event
+     * Sets the raw amount of damage caused by the event.
+     * <p>
+     * For compatibility this also recalculates the modifiers and scales
+     * them by the difference between the modifier for the previous damage
+     * value and the new one.
      *
-     * @param damage The amount of damage caused by the event
+     * @param damage The raw amount of damage caused by the event
      */
     public void setDamage(double damage) {
-        this.damage = damage;
+        // These have to happen in the same order as the server calculates them, keep the enum sorted
+        double remaining = damage;
+        double oldRemaining = getDamage(DamageModifier.BASE);
+        for (DamageModifier modifier : MODIFIERS) {
+            if (!isApplicable(modifier)) {
+                continue;
+            }
+
+            Function<? super Double, Double> modifierFunction = modifierFunctions.get(modifier);
+            double newVanilla = modifierFunction.apply(remaining);
+            double oldVanilla = modifierFunction.apply(oldRemaining);
+            double difference = oldVanilla - newVanilla;
+
+            // Don't allow value to cross zero, assume zero values should be negative
+            double old = getDamage(modifier);
+            if (old > 0) {
+                setDamage(modifier, Math.max(0, old - difference));
+            } else {
+                setDamage(modifier, Math.min(0, old - difference));
+            }
+            remaining += newVanilla;
+            oldRemaining += oldVanilla;
+        }
+
+        setDamage(DamageModifier.BASE, damage);
     }
 
     /**
@@ -89,6 +221,52 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
         return handlers;
     }
 
+    /**
+     * An enum to specify the types of modifier
+     */
+    public enum DamageModifier {
+        /**
+         * This represents the amount of damage being done, also known as the
+         * raw {@link EntityDamageEvent#getDamage()}.
+         */
+        BASE,
+        /**
+         * This represents the damage reduced by a wearing a helmet when hit
+         * by a falling block.
+         */
+        HARD_HAT,
+        /**
+         * This represents  the damage reduction caused by blocking, only present for
+         * {@link Player Players}.
+         */
+        BLOCKING,
+        /**
+         * This represents the damage reduction caused by wearing armor.
+         */
+        ARMOR,
+        /**
+         * This represents the damage reduction caused by the Resistance potion effect.
+         */
+        RESISTANCE,
+        /**
+         * This represents the damage reduction caused by the combination of:
+         * <ul>
+         * <li>
+         *     Armor enchantments
+         * </li><li>
+         *     Witch's potion resistance
+         * </li>
+         * </ul>
+         */
+        MAGIC,
+        /**
+         * This represents the damage reduction caused by the absorption potion
+         * effect.
+         */
+        ABSORPTION,
+        ;
+    }
+
     /**
      * An enum to specify the cause of the damage
      */

src/main/java/org/bukkit/event/entity/PlayerDeathEvent.java

@@ -14,6 +14,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
     private int newLevel = 0;
     private int newTotalExp = 0;
     private boolean keepLevel = false;
+    private boolean keepInventory = false;
 
     public PlayerDeathEvent(final Player player, final List<ItemStack> drops, final int droppedExp, final String deathMessage) {
         this(player, drops, droppedExp, 0, deathMessage);
@@ -135,4 +136,22 @@ public class PlayerDeathEvent extends EntityDeathEvent {
     public void setKeepLevel(boolean keepLevel) {
         this.keepLevel = keepLevel;
     }
+
+    /**
+     * Sets if the Player keeps inventory on death.
+     *
+     * @param keepInventory True to keep the inventory
+     */
+    public void setKeepInventory(boolean keepInventory) {
+        this.keepInventory = keepInventory;
+    }
+
+    /**
+     * Gets if the Player keeps inventory on death.
+     *
+     * @return True if the player keeps inventory on death
+     */
+    public boolean getKeepInventory() {
+        return keepInventory;
+    }
 }

src/main/java/org/bukkit/event/player/PlayerChatEvent.java

@@ -1,6 +1,5 @@
 package org.bukkit.event.player;
 
-import java.util.Arrays;
 import java.util.HashSet;
 import java.util.Set;
 
@@ -33,7 +32,7 @@ public class PlayerChatEvent extends PlayerEvent implements Cancellable {
         super(player);
         this.message = message;
         this.format = "<%1$s> %2$s";
-        this.recipients = new HashSet<Player>(Arrays.asList(player.getServer().getOnlinePlayers()));
+        this.recipients = new HashSet<Player>(player.getServer().getOnlinePlayers());
     }
 
     public PlayerChatEvent(final Player player, final String message, final String format, final Set<Player> recipients) {

src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java

@@ -1,6 +1,5 @@
 package org.bukkit.event.player;
 
-import java.util.Arrays;
 import java.util.HashSet;
 import java.util.Set;
 
@@ -55,7 +54,7 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell
 
     public PlayerCommandPreprocessEvent(final Player player, final String message) {
         super(player);
-        this.recipients = new HashSet<Player>(Arrays.asList(player.getServer().getOnlinePlayers()));
+        this.recipients = new HashSet<Player>(player.getServer().getOnlinePlayers());
         this.message = message;
     }
 

src/main/java/org/bukkit/event/player/PlayerFishEvent.java

@@ -37,10 +37,13 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
     }
 
     /**
-     * Gets the entity caught by the player
+     * Gets the entity caught by the player.
+     * <p>
+     * If player has fished successfully, the result may be cast to {@link
+     * Item}.
      *
-     * @return Entity caught by the player, null if fishing, bobber has gotten
+     * @return Entity caught by the player, Entity if fishing, and null if
-     *     stuck in the ground or nothing has been caught
+     *     bobber has gotten stuck in the ground or nothing has been caught
      */
     public Entity getCaught() {
         return entity;

src/main/java/org/bukkit/scheduler/BukkitRunnable.java

@@ -29,7 +29,7 @@ public abstract class BukkitRunnable implements Runnable {
      */
     public synchronized BukkitTask runTask(Plugin plugin) throws IllegalArgumentException, IllegalStateException {
         checkState();
-        return setupId(Bukkit.getScheduler().runTask(plugin, this));
+        return setupId(Bukkit.getScheduler().runTask(plugin, (Runnable) this));
     }
 
     /**
@@ -46,7 +46,7 @@ public abstract class BukkitRunnable implements Runnable {
      */
     public synchronized BukkitTask runTaskAsynchronously(Plugin plugin) throws IllegalArgumentException, IllegalStateException  {
         checkState();
-        return setupId(Bukkit.getScheduler().runTaskAsynchronously(plugin, this));
+        return setupId(Bukkit.getScheduler().runTaskAsynchronously(plugin, (Runnable) this));
     }
 
     /**
@@ -61,7 +61,7 @@ public abstract class BukkitRunnable implements Runnable {
      */
     public synchronized BukkitTask runTaskLater(Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
         checkState();
-        return setupId(Bukkit.getScheduler().runTaskLater(plugin, this, delay));
+        return setupId(Bukkit.getScheduler().runTaskLater(plugin, (Runnable) this, delay));
     }
 
     /**
@@ -80,7 +80,7 @@ public abstract class BukkitRunnable implements Runnable {
      */
     public synchronized BukkitTask runTaskLaterAsynchronously(Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
         checkState();
-        return setupId(Bukkit.getScheduler().runTaskLaterAsynchronously(plugin, this, delay));
+        return setupId(Bukkit.getScheduler().runTaskLaterAsynchronously(plugin, (Runnable) this, delay));
     }
 
     /**
@@ -97,7 +97,7 @@ public abstract class BukkitRunnable implements Runnable {
      */
     public synchronized BukkitTask runTaskTimer(Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException  {
         checkState();
-        return setupId(Bukkit.getScheduler().runTaskTimer(plugin, this, delay, period));
+        return setupId(Bukkit.getScheduler().runTaskTimer(plugin, (Runnable) this, delay, period));
     }
 
     /**
@@ -119,7 +119,7 @@ public abstract class BukkitRunnable implements Runnable {
      */
     public synchronized BukkitTask runTaskTimerAsynchronously(Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException  {
         checkState();
-        return setupId(Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, this, delay, period));
+        return setupId(Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, (Runnable) this, delay, period));
     }
 
     /**

src/main/java/org/bukkit/scheduler/BukkitScheduler.java

@@ -19,6 +19,12 @@ public interface BukkitScheduler {
      */
     public int scheduleSyncDelayedTask(Plugin plugin, Runnable task, long delay);
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
+     */
+    @Deprecated
+    public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task, long delay);
+
     /**
      * Schedules a once off task to occur as soon as possible.
      * <p>
@@ -30,6 +36,12 @@ public interface BukkitScheduler {
      */
     public int scheduleSyncDelayedTask(Plugin plugin, Runnable task);
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
+     */
+    @Deprecated
+    public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task);
+
     /**
      * Schedules a repeating task.
      * <p>
@@ -43,6 +55,12 @@ public interface BukkitScheduler {
      */
     public int scheduleSyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
+     */
+    @Deprecated
+    public int scheduleSyncRepeatingTask(Plugin plugin, BukkitRunnable task, long delay, long period);
+
     /**
      * <b>Asynchronous tasks should never access any API in Bukkit. Great care
      * should be taken to assure the thread-safety of asynchronous tasks.</b>
@@ -188,6 +206,12 @@ public interface BukkitScheduler {
      */
     public BukkitTask runTask(Plugin plugin, Runnable task) throws IllegalArgumentException;
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
+     */
+    @Deprecated
+    public BukkitTask runTask(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
+
     /**
      * <b>Asynchronous tasks should never access any API in Bukkit. Great care
      * should be taken to assure the thread-safety of asynchronous tasks.</b>
@@ -202,6 +226,12 @@ public interface BukkitScheduler {
      */
     public BukkitTask runTaskAsynchronously(Plugin plugin, Runnable task) throws IllegalArgumentException;
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTaskAsynchronously(Plugin)}
+     */
+    @Deprecated
+    public BukkitTask runTaskAsynchronously(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
+
     /**
      * Returns a task that will run after the specified number of server
      * ticks.
@@ -215,6 +245,12 @@ public interface BukkitScheduler {
      */
     public BukkitTask runTaskLater(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
+     */
+    @Deprecated
+    public BukkitTask runTaskLater(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
+
     /**
      * <b>Asynchronous tasks should never access any API in Bukkit. Great care
      * should be taken to assure the thread-safety of asynchronous tasks.</b>
@@ -231,6 +267,12 @@ public interface BukkitScheduler {
      */
     public BukkitTask runTaskLaterAsynchronously(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTaskLaterAsynchronously(Plugin, long)}
+     */
+    @Deprecated
+    public BukkitTask runTaskLaterAsynchronously(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
+
     /**
      * Returns a task that will repeatedly run until cancelled, starting after
      * the specified number of server ticks.
@@ -245,6 +287,12 @@ public interface BukkitScheduler {
      */
     public BukkitTask runTaskTimer(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
 
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
+     */
+    @Deprecated
+    public BukkitTask runTaskTimer(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
+
     /**
      * <b>Asynchronous tasks should never access any API in Bukkit. Great care
      * should be taken to assure the thread-safety of asynchronous tasks.</b>
@@ -262,4 +310,10 @@ public interface BukkitScheduler {
      * @throws IllegalArgumentException if task is null
      */
     public BukkitTask runTaskTimerAsynchronously(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
+
+    /**
+     * @deprecated Use {@link BukkitRunnable#runTaskTimerAsynchronously(Plugin, long, long)}
+     */
+    @Deprecated
+    public BukkitTask runTaskTimerAsynchronously(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
 }