Provide a faster way to get a location. Adds BUKKIT-3120

Currently when a plugin wants to get the location of something it calls
getLocation() which returns a new Location object. In some scenarios this
can cause enough object creation/destruction churn to be a significant
overhead. For this cases we add a method that updates a provided Location
object so there is no object creation done. This allows well written code
to work on several locations with only a single Location object getting
created.

Providing a more efficient way to set a location was also looked at but
the current solution is the fastest we can provide. You are not required
to create a new Location object every time you want to set something's
location so, with proper design, you can set locations with only a single
Location object being created.

src/main/java/org/bukkit/block/Block.java

@@ -137,6 +137,14 @@ public interface Block extends Metadatable {
      */
     Location getLocation();
 
+    /**
+     * Stores the location of the block in the provided Location object.<br />
+     * If the provided Location is null this method does nothing and returns null.
+     *
+     * @return The Location object provided or null
+     */
+    Location getLocation(Location loc);
+
     /**
      * Gets the chunk which contains this block
      *

src/main/java/org/bukkit/block/BlockState.java

@@ -87,6 +87,14 @@ public interface BlockState extends Metadatable {
      */
     Location getLocation();
 
+    /**
+     * Stores the location of this block in the provided Location object.<br />
+     * If the provided Location is null this method does nothing and returns null.
+     *
+     * @return The Location object provided or null
+     */
+    Location getLocation(Location loc);
+
     /**
      * Gets the chunk which contains this block
      *

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

@@ -24,6 +24,14 @@ public interface Entity extends Metadatable {
      */
     public Location getLocation();
 
+    /**
+     * Stores the entity's current position in the provided Location object.<br />
+     * If the provided Location is null this method does nothing and returns null.
+     *
+     * @return The Location object provided or null
+     */
+    public Location getLocation(Location loc);
+
     /**
      * Sets this entity's velocity
      *