From c87e48bb00a1f7b2bc927ac2a97802ea52ebbf4d Mon Sep 17 00:00:00 2001
From: Bukkit/Spigot <noreply+git-bukkit@papermc.io>
Date: Fri, 7 Dec 2012 19:48:19 -0600
Subject: [PATCH] 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.

By: Travis Watkins <amaranth@ubuntu.com>
---
 paper-api/src/main/java/org/bukkit/block/Block.java      | 8 ++++++++
 paper-api/src/main/java/org/bukkit/block/BlockState.java | 8 ++++++++
 paper-api/src/main/java/org/bukkit/entity/Entity.java    | 8 ++++++++
 3 files changed, 24 insertions(+)

diff --git a/paper-api/src/main/java/org/bukkit/block/Block.java b/paper-api/src/main/java/org/bukkit/block/Block.java
index ffc20d81f8..933b90fe1e 100644
--- a/paper-api/src/main/java/org/bukkit/block/Block.java
+++ b/paper-api/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/paper-api/src/main/java/org/bukkit/block/BlockState.java b/paper-api/src/main/java/org/bukkit/block/BlockState.java
index c727d0e0e1..08b10e6fa6 100644
--- a/paper-api/src/main/java/org/bukkit/block/BlockState.java
+++ b/paper-api/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/paper-api/src/main/java/org/bukkit/entity/Entity.java b/paper-api/src/main/java/org/bukkit/entity/Entity.java
index 9058429b6d..a9df5c5c8a 100644
--- a/paper-api/src/main/java/org/bukkit/entity/Entity.java
+++ b/paper-api/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
      *