From 2ea133bb9923015f1c07217440840a1eb18a4385 Mon Sep 17 00:00:00 2001
From: Travis Watkins <amaranth@ubuntu.com>
Date: Fri, 7 Dec 2012 19:48:19 -0600
Subject: 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      | 8 ++++++++
 src/main/java/org/bukkit/block/BlockState.java | 8 ++++++++
 src/main/java/org/bukkit/entity/Entity.java    | 8 ++++++++
 3 files changed, 24 insertions(+)

(limited to 'src/main/java/org')

diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
index ffc20d81..933b90fe 100644
--- a/src/main/java/org/bukkit/block/Block.java
+++ b/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
      *
diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java
index c727d0e0..08b10e6f 100644
--- a/src/main/java/org/bukkit/block/BlockState.java
+++ b/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
      *
diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java
index 9058429b..a9df5c5c 100644
--- a/src/main/java/org/bukkit/entity/Entity.java
+++ b/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
      *
-- 
cgit v1.2.3