[Bleeding] Added a Metadata framework for Entities, Blocks, and Worlds

This metadata implementation has the following features:

- All metadata is lazy. Metadata values are not actually computed until another plugin requests them. Memory and CPU are conserved by not computing and storing unnecessary metadata values.

- All metadata is cached. Once a metadata value is computed its value is cached in the metadata store to prevent further unnecessary computation. An invalidation mechanism is provided to flush the cache and force recompilation of metadata values.

- All metadata is stored in basic data types. Convenience methods in the MetadataValue class allow for the conversion of metadata data types when possible. Restricting metadata to basic data types prevents the accidental linking of large object graphs into metadata. Metadata is persistent across the lifetime of the application and adding large object graphs would damage garbage collector performance.

- Metadata access is thread safe. Care has been taken to protect the internal data structures and access them in a thread safe manner.

- Metadata is exposed for all objects that descend from Entity, Block, and World. All Entity and World metadata is stored at the Server  level and all Block metadata is stored at the World level.

- Metadata is NOT keyed on references to original objects - instead metadata is keyed off of unique fields within those objects. Doing this allows metadata to exist for blocks that are in chunks not currently in memory. Additionally, Player objects are keyed off of player name so that Player metadata remains consistent between logins.

- Metadata convenience methods have been added to all Entities, Players, Blocks, BlockStates, and World allowing direct access to an individual instance's metadata.

- Players and OfflinePlayers share a single metadata store, allowing player metadata to be manipulated regardless of the player's current online status.

7 files changed, 444 insertions, 4 deletions

diff --git a/src/test/java/org/bukkit/metadata/FixedMetadataValueTest.java b/src/test/java/org/bukkit/metadata/FixedMetadataValueTest.java
new file mode 100644
index 00000000..0844f975
--- /dev/null
+++ b/src/test/java/org/bukkit/metadata/FixedMetadataValueTest.java
@@ -0,0 +1,30 @@
+package org.bukkit.metadata;
+
+import static org.junit.Assert.assertEquals;
+
+import org.bukkit.plugin.Plugin;
+import org.bukkit.plugin.messaging.TestPlugin;
+import org.junit.Test;
+
+public class FixedMetadataValueTest {
+    private Plugin plugin = new TestPlugin("X");
+    private FixedMetadataValue subject;
+
+    private void valueEquals(Object value) {
+        subject = new FixedMetadataValue(plugin, value);
+        assertEquals(value, subject.value());
+    }
+
+    @Test
+    public void testTypes() {
+        valueEquals(10);
+        valueEquals(0.1);
+        valueEquals("TEN");
+        valueEquals(true);
+        valueEquals(null);
+        valueEquals((float) 10.5);
+        valueEquals((long) 10);
+        valueEquals((short) 10);
+        valueEquals((byte) 10);
+    }
+}
diff --git a/src/test/java/org/bukkit/metadata/LazyMetadataValueTest.java b/src/test/java/org/bukkit/metadata/LazyMetadataValueTest.java
new file mode 100644
index 00000000..ece6a0f4
--- /dev/null
+++ b/src/test/java/org/bukkit/metadata/LazyMetadataValueTest.java
@@ -0,0 +1,135 @@
+package org.bukkit.metadata;
+
+import org.bukkit.plugin.messaging.TestPlugin;
+import org.junit.Test;
+
+import java.util.concurrent.Callable;
+
+import static org.junit.Assert.*;
+
+public class LazyMetadataValueTest {
+    private LazyMetadataValue subject;
+    private TestPlugin plugin = new TestPlugin("x");
+
+    @Test
+    public void testLazyInt() {
+        int value = 10;
+        subject = makeSimpleCallable(value);
+
+        assertEquals(value, subject.value());
+    }
+
+    @Test
+    public void testLazyDouble() {
+        double value = 10.5;
+        subject = makeSimpleCallable(value);
+
+        assertEquals(value, (Double)subject.value(), 0.01);
+    }
+
+    @Test
+    public void testLazyString() {
+        String value = "TEN";
+        subject = makeSimpleCallable(value);
+
+        assertEquals(value, subject.value());
+    }
+
+    @Test
+    public void testLazyBoolean() {
+        boolean value = false;
+        subject = makeSimpleCallable(value);
+
+        assertEquals(value, subject.value());
+    }
+
+    @Test(expected=MetadataEvaluationException.class)
+    public void testEvalException() {
+        subject = new LazyMetadataValue(plugin, LazyMetadataValue.CacheStrategy.CACHE_AFTER_FIRST_EVAL, new Callable<Object>() {
+            public Object call() throws Exception {
+                throw new RuntimeException("Gotcha!");
+            }
+        });
+        subject.value();
+    }
+
+    @Test
+    public void testCacheStrategyCacheAfterFirstEval() {
+        final Counter counter = new Counter();
+        final int value = 10;
+        subject = new LazyMetadataValue(plugin, LazyMetadataValue.CacheStrategy.CACHE_AFTER_FIRST_EVAL, new Callable<Object>() {
+            public Object call() throws Exception {
+                counter.increment();
+                return value;
+            }
+        });
+
+        subject.value();
+        subject.value();
+        assertEquals(value, subject.value());
+        assertEquals(1, counter.value());
+
+        subject.invalidate();
+        subject.value();
+        assertEquals(2, counter.value());
+    }
+
+    @Test
+    public void testCacheStrategyNeverCache() {
+        final Counter counter = new Counter();
+        final int value = 10;
+        subject = new LazyMetadataValue(plugin, LazyMetadataValue.CacheStrategy.NEVER_CACHE, new Callable<Object>() {
+            public Object call() throws Exception {
+                counter.increment();
+                return value;
+            }
+        });
+
+        subject.value();
+        subject.value();
+        assertEquals(value, subject.value());
+        assertEquals(3, counter.value());
+    }
+
+    @Test
+    public void testCacheStrategyEternally() {
+        final Counter counter = new Counter();
+        final int value = 10;
+        subject = new LazyMetadataValue(plugin, LazyMetadataValue.CacheStrategy.CACHE_ETERNALLY, new Callable<Object>() {
+            public Object call() throws Exception {
+                counter.increment();
+                return value;
+            }
+        });
+
+        subject.value();
+        subject.value();
+        assertEquals(value, subject.value());
+        assertEquals(1, counter.value());
+
+        subject.invalidate();
+        subject.value();
+        assertEquals(value, subject.value());
+        assertEquals(1, counter.value());
+    }
+
+    private LazyMetadataValue makeSimpleCallable(final Object value) {
+        return new LazyMetadataValue(plugin, new Callable<Object>() {
+            public Object call() throws Exception {
+                return value;
+            }
+        });
+    }
+
+    private class Counter {
+        private int c = 0;
+
+        public void increment() {
+            c++;
+        }
+
+        public int value() {
+            return c;
+        }
+    }
+}
diff --git a/src/test/java/org/bukkit/metadata/MetadataConversionTest.java b/src/test/java/org/bukkit/metadata/MetadataConversionTest.java
new file mode 100644
index 00000000..428768ad
--- /dev/null
+++ b/src/test/java/org/bukkit/metadata/MetadataConversionTest.java
@@ -0,0 +1,103 @@
+//    Copyright (C) 2011  Ryan Michela
+//
+//    This program is free software: you can redistribute it and/or modify
+//    it under the terms of the GNU General Public License as published by
+//    the Free Software Foundation, either version 3 of the License, or
+//    (at your option) any later version.
+//
+//    This program is distributed in the hope that it will be useful,
+//    but WITHOUT ANY WARRANTY; without even the implied warranty of
+//    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//    GNU General Public License for more details.
+//
+//    You should have received a copy of the GNU General Public License
+//    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package org.bukkit.metadata;
+
+import org.bukkit.plugin.Plugin;
+import org.bukkit.plugin.messaging.TestPlugin;
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+
+/**
+ */
+public class MetadataConversionTest {
+    private Plugin plugin = new TestPlugin("x");
+    private FixedMetadataValue subject;
+
+    private void setSubject(Object value) {
+        subject = new FixedMetadataValue(plugin, value);
+    }
+
+    @Test
+    public void testFromInt() {
+        setSubject(10);
+
+        assertEquals(10, subject.asInt());
+        assertEquals(10, subject.asFloat(), 0.000001);
+        assertEquals(10, subject.asDouble(), 0.000001);
+        assertEquals(10, subject.asLong());
+        assertEquals(10, subject.asShort());
+        assertEquals(10, subject.asByte());
+        assertEquals(true, subject.asBoolean());
+        assertEquals("10", subject.asString());
+    }
+
+    @Test
+    public void testFromFloat() {
+        setSubject(10.5);
+
+        assertEquals(10, subject.asInt());
+        assertEquals(10.5, subject.asFloat(), 0.000001);
+        assertEquals(10.5, subject.asDouble(), 0.000001);
+        assertEquals(10, subject.asLong());
+        assertEquals(10, subject.asShort());
+        assertEquals(10, subject.asByte());
+        assertEquals(true, subject.asBoolean());
+        assertEquals("10.5", subject.asString());
+    }
+
+    @Test
+    public void testFromNumericString() {
+        setSubject("10");
+
+        assertEquals(10, subject.asInt());
+        assertEquals(10, subject.asFloat(), 0.000001);
+        assertEquals(10, subject.asDouble(), 0.000001);
+        assertEquals(10, subject.asLong());
+        assertEquals(10, subject.asShort());
+        assertEquals(10, subject.asByte());
+        assertEquals(false, subject.asBoolean());
+        assertEquals("10", subject.asString());
+    }
+
+    @Test
+    public void testFromNonNumericString() {
+        setSubject("true");
+
+        assertEquals(0, subject.asInt());
+        assertEquals(0, subject.asFloat(), 0.000001);
+        assertEquals(0, subject.asDouble(), 0.000001);
+        assertEquals(0, subject.asLong());
+        assertEquals(0, subject.asShort());
+        assertEquals(0, subject.asByte());
+        assertEquals(true, subject.asBoolean());
+        assertEquals("true", subject.asString());
+    }
+
+    @Test
+    public void testFromNull() {
+        setSubject(null);
+
+        assertEquals(0, subject.asInt());
+        assertEquals(0, subject.asFloat(), 0.000001);
+        assertEquals(0, subject.asDouble(), 0.000001);
+        assertEquals(0, subject.asLong());
+        assertEquals(0, subject.asShort());
+        assertEquals(0, subject.asByte());
+        assertEquals(false, subject.asBoolean());
+        assertEquals("", subject.asString());
+    }
+}
diff --git a/src/test/java/org/bukkit/metadata/MetadataStoreTest.java b/src/test/java/org/bukkit/metadata/MetadataStoreTest.java
new file mode 100644
index 00000000..98a96423
--- /dev/null
+++ b/src/test/java/org/bukkit/metadata/MetadataStoreTest.java
@@ -0,0 +1,127 @@
+package org.bukkit.metadata;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+import java.util.List;
+import java.util.concurrent.Callable;
+
+import org.bukkit.plugin.Plugin;
+import org.bukkit.plugin.messaging.TestPlugin;
+import org.junit.Test;
+
+public class MetadataStoreTest {
+    private Plugin pluginX = new TestPlugin("x");
+    private Plugin pluginY = new TestPlugin("y");
+
+    StringMetadataStore subject = new StringMetadataStore();
+
+    @Test
+    public void testMetadataStore() {
+        subject.setMetadata("subject", "key", new FixedMetadataValue(pluginX, 10));
+
+        assertTrue(subject.hasMetadata("subject", "key"));
+        List<MetadataValue> values = subject.getMetadata("subject", "key");
+        assertEquals(10, values.get(0).value());
+    }
+
+    @Test
+    public void testMetadataNotPresent() {
+        assertFalse(subject.hasMetadata("subject", "key"));
+        List<MetadataValue> values = subject.getMetadata("subject", "key");
+        assertTrue(values.isEmpty());
+    }
+
+    @Test
+    public void testInvalidateAll() {
+        final Counter counter = new Counter();
+
+        subject.setMetadata("subject", "key", new LazyMetadataValue(pluginX, new Callable<Object>() {
+            public Object call() throws Exception {
+                counter.increment();
+                return 10;
+            }
+        }));
+
+        assertTrue(subject.hasMetadata("subject", "key"));
+        subject.getMetadata("subject", "key").get(0).value();
+        subject.invalidateAll(pluginX);
+        subject.getMetadata("subject", "key").get(0).value();
+        assertEquals(2, counter.value());
+    }
+
+    @Test
+    public void testInvalidateAllButActuallyNothing() {
+        final Counter counter = new Counter();
+
+        subject.setMetadata("subject", "key", new LazyMetadataValue(pluginX, new Callable<Object>() {
+            public Object call() throws Exception {
+                counter.increment();
+                return 10;
+            }
+        }));
+
+        assertTrue(subject.hasMetadata("subject", "key"));
+        subject.getMetadata("subject", "key").get(0).value();
+        subject.invalidateAll(pluginY);
+        subject.getMetadata("subject", "key").get(0).value();
+        assertEquals(1, counter.value());
+    }
+
+    @Test
+    public void testMetadataReplace() {
+        subject.setMetadata("subject", "key", new FixedMetadataValue(pluginX, 10));
+        subject.setMetadata("subject", "key", new FixedMetadataValue(pluginY, 10));
+        subject.setMetadata("subject", "key", new FixedMetadataValue(pluginX, 20));
+
+        for (MetadataValue mv : subject.getMetadata("subject", "key")) {
+            if (mv.getOwningPlugin().equals(pluginX)) {
+                assertEquals(20, mv.value());
+            }
+            if (mv.getOwningPlugin().equals(pluginY)) {
+                assertEquals(10, mv.value());
+            }
+        }
+    }
+
+    @Test
+    public void testMetadataRemove() {
+        subject.setMetadata("subject", "key", new FixedMetadataValue(pluginX, 10));
+        subject.setMetadata("subject", "key", new FixedMetadataValue(pluginY, 20));
+        subject.removeMetadata("subject", "key", pluginX);
+
+        assertTrue(subject.hasMetadata("subject", "key"));
+        assertEquals(1, subject.getMetadata("subject", "key").size());
+        assertEquals(20, subject.getMetadata("subject", "key").get(0).value());
+    }
+
+    @Test
+    public void testMetadataRemoveForNonExistingPlugin() {
+        subject.setMetadata("subject", "key", new FixedMetadataValue(pluginX, 10));
+        subject.removeMetadata("subject", "key", pluginY);
+
+        assertTrue(subject.hasMetadata("subject", "key"));
+        assertEquals(1, subject.getMetadata("subject", "key").size());
+        assertEquals(10, subject.getMetadata("subject", "key").get(0).value());
+    }
+
+    private class StringMetadataStore extends MetadataStoreBase<String> implements MetadataStore<String> {
+        @Override
+        protected String disambiguate(String subject, String metadataKey) {
+            return subject + ":" + metadataKey;
+        }
+    }
+
+    private class Counter {
+        int c = 0;
+
+        public void increment() {
+            c++;
+        }
+
+        public int value() {
+            return c;
+        }
+    }
+}
diff --git a/src/test/java/org/bukkit/plugin/messaging/StandardMessengerTest.java b/src/test/java/org/bukkit/plugin/messaging/StandardMessengerTest.java
index 52e4a0fb..ee3d8acf 100644
--- a/src/test/java/org/bukkit/plugin/messaging/StandardMessengerTest.java
+++ b/src/test/java/org/bukkit/plugin/messaging/StandardMessengerTest.java
@@ -11,8 +11,9 @@ public class StandardMessengerTest {
         return new StandardMessenger();
     }
 
+    private int count = 0;
     public TestPlugin getPlugin() {
-        return new TestPlugin();
+        return new TestPlugin("" + count++);
     }
 
     @Test
diff --git a/src/test/java/org/bukkit/plugin/messaging/TestPlayer.java b/src/test/java/org/bukkit/plugin/messaging/TestPlayer.java
index 4ecd9745..da6b7d81 100644
--- a/src/test/java/org/bukkit/plugin/messaging/TestPlayer.java
+++ b/src/test/java/org/bukkit/plugin/messaging/TestPlayer.java
@@ -22,6 +22,7 @@ import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.PlayerInventory;
 import org.bukkit.map.MapView;
+import org.bukkit.metadata.MetadataValue;
 import org.bukkit.permissions.Permission;
 import org.bukkit.permissions.PermissionAttachment;
 import org.bukkit.permissions.PermissionAttachmentInfo;
@@ -658,4 +659,20 @@ public class TestPlayer implements Player {
     public EntityType getType() {
         return EntityType.PLAYER;
     }
+
+    public void setMetadata(String metadataKey, MetadataValue newMetadataValue) {
+        throw new UnsupportedOperationException("Not supported yet.");
+    }
+
+    public List<MetadataValue> getMetadata(String metadataKey) {
+        throw new UnsupportedOperationException("Not supported yet.");
+    }
+
+    public boolean hasMetadata(String metadataKey) {
+        throw new UnsupportedOperationException("Not supported yet.");
+    }
+
+    public void removeMetadata(String metadataKey, Plugin owningPlugin) {
+        throw new UnsupportedOperationException("Not supported yet.");
+    }
 }
diff --git a/src/test/java/org/bukkit/plugin/messaging/TestPlugin.java b/src/test/java/org/bukkit/plugin/messaging/TestPlugin.java
index a03581c3..f14e2e75 100644
--- a/src/test/java/org/bukkit/plugin/messaging/TestPlugin.java
+++ b/src/test/java/org/bukkit/plugin/messaging/TestPlugin.java
@@ -1,8 +1,8 @@
 package org.bukkit.plugin.messaging;
 
-import com.avaje.ebean.EbeanServer;
 import java.io.File;
 import java.io.InputStream;
+
 import org.bukkit.Server;
 import org.bukkit.command.Command;
 import org.bukkit.command.CommandSender;
@@ -13,19 +13,31 @@ import org.bukkit.plugin.PluginDescriptionFile;
 import org.bukkit.plugin.PluginLoader;
 import org.bukkit.plugin.PluginLogger;
 
-public class TestPlugin implements Plugin {
+import com.avaje.ebean.EbeanServer;
+
+public class TestPlugin extends Plugin {
     private boolean enabled = true;
 
+    final private String pluginName;
+
+    public TestPlugin(String pluginName) {
+        this.pluginName = pluginName;
+    }
+
     public void setEnabled(boolean enabled) {
         this.enabled = enabled;
     }
 
+    public String getName() {
+        return pluginName;
+    }
+
     public File getDataFolder() {
         throw new UnsupportedOperationException("Not supported.");
     }
 
     public PluginDescriptionFile getDescription() {
-        throw new UnsupportedOperationException("Not supported.");
+        return new PluginDescriptionFile(pluginName, "1.0", "test.test");
     }
 
     public FileConfiguration getConfig() {
@@ -100,4 +112,19 @@ public class TestPlugin implements Plugin {
         throw new UnsupportedOperationException("Not supported.");
     }
 
+    @Override
+    public int hashCode() {
+        return getName().hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj)
+            return true;
+        if (obj == null)
+            return false;
+        if (getClass() != obj.getClass())
+            return false;
+        return getName().equals(((TestPlugin) obj).getName());
+    }
 }