[B+C] Add ItemMeta.hasCustomData/getCustomData. Adds BUKKIT-3221

src/main/java/org/bukkit/inventory/ItemStack.java

@@ -12,6 +12,7 @@
 import org.bukkit.enchantments.Enchantment;
 import org.bukkit.inventory.meta.ItemMeta;
 import org.bukkit.material.MaterialData;
+import org.bukkit.plugin.Plugin;
 
 /**
  * Represents a stack of items
@@ -600,4 +601,40 @@ private boolean setItemMeta0(ItemMeta itemMeta, Material material) {
 
         return true;
     }
+
+    /**
+     * This can be overridden to provide an efficient quick check to
+     * see if this ItemStack has a specific key in its metadata store,
+     * without actually unpacking the ItemMeta object.
+     * <p>
+     * Use this in place of getItemMeta().hasMetadata("field") for simple first-pass
+     * checks for data, if you don't necessarily need to unpack the data.
+     * <p>
+     * The default implementation defers to ItemMeta.
+     *
+     * @param key The String key to check for
+     * @return True if getItemMeta().hasMetadata(key)
+     */
+    public boolean hasMetadata(String key) {
+        return meta != null && meta.hasMetadata(key);
+    }
+
+    /**
+     * This can be overridden to provide an efficient quick check to
+     * see if this ItemStack has a specific key in its metadata store
+     * for a specific plugin, without actually unpacking the ItemMeta object.
+     * <p>
+     * Use this in place of getItemMeta().hasMetadata("field", plugin) for
+     * simple first-pass checks for data, if you don't necessarily need to
+     * unpack the data.
+     * <p>
+     * The default implementation defers to ItemMeta.
+     *
+     * @param key The String key to check for
+     * @param plugin The Plugin for which to check for data
+     * @return True if getItemMeta().hasMetadata(key)
+     */
+    public boolean hasMetadata(String key, Plugin plugin) {
+        return meta != null && meta.hasMetadata(key, plugin);
+    }
 }

src/main/java/org/bukkit/inventory/meta/ItemMeta.java

@@ -3,16 +3,23 @@
 import java.util.List;
 import java.util.Map;
 
+import org.bukkit.configuration.ConfigurationSection;
 import org.bukkit.configuration.serialization.ConfigurationSerializable;
 import org.bukkit.enchantments.Enchantment;
+import org.bukkit.metadata.MetadataValue;
+import org.bukkit.metadata.Metadatable;
+import org.bukkit.plugin.Plugin;
 
 /**
  * This type represents the storage mechanism for auxiliary item data.
  * <p>
  * An implementation will handle the creation and application for ItemMeta.
  * This class should not be implemented by a plugin in a live environment.
+ * <p>
+ * The implementing class should implement Metadatable as a persistent data store attached
+ * to each ItemStack, and only accept PersistentMetadataValue entries.
  */
-public interface ItemMeta extends Cloneable, ConfigurationSerializable {
+public interface ItemMeta extends Cloneable, ConfigurationSerializable, Metadatable {
 
     /**
      * Checks for existence of a display name.
@@ -63,6 +70,34 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable {
      */
     void setLore(List<String> lore);
 
+    /**
+     * Check to see if the Metadatable store contains any data for any
+     * Plugin.
+     *
+     * @return true if there is any custom data present
+     */
+    public boolean hasMetadata();
+
+    /**
+     * Check to see if the Metadatable store contains a specific key
+     * for a specific Plugin.
+     *
+     * @param key the String key to check for
+     * @param plugin the Plugin for which to check for data
+     * @return true if the specified key is registered in this store
+     *   for the specified Plugin
+     */
+    public boolean hasMetadata(String key, Plugin plugin);
+
+    /**
+     * Return a single metadata value for a given key and Plugin.
+     *
+     * @param metadataKey the unique metadata key being sought
+     * @param owningPlugin the plugin that owns the data being sought
+     * @return the requested value, or null if not found
+     */
+    public MetadataValue getMetadata(String metadataKey, Plugin owningPlugin);
+
     /**
      * Checks for the existence of any enchantments.
      *
@@ -124,6 +159,23 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable {
     */
     boolean hasConflictingEnchant(Enchantment ench);
 
+    /**
+     * See if this item is glowing for any reason.
+     * This could be due to enchantments, or to having its gow effect set with setGlowEffect(true)
+     *
+     * @return true if this item is glowing
+     */
+    boolean hasGlowEffect();
+
+    /**
+     * Force this item to glow, or remove an item's glow.
+     *
+     * Glow can only be removed this way if there are no enchantments on the item.
+     *
+     * @param glow if true, a visual glow effect will be added to the item, effect removed if false
+     */
+    void setGlowEffect(boolean glow);
+
     @SuppressWarnings("javadoc")
     ItemMeta clone();
 }

src/main/java/org/bukkit/metadata/PersistentMetadataValue.java

@@ -0,0 +1,63 @@
+package org.bukkit.metadata;
+
+import org.bukkit.configuration.serialization.ConfigurationSerializable;
+import org.bukkit.plugin.Plugin;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A PersistentMetadataValue is a special case metadata item that may
+ * only contain ConfigurationSerializable Objects, Lists, Maps or
+ * basic Object types.
+ * <p>
+ * This class is primarily here to serve as a reminder that
+ * a persistent data store must hold serializable data.
+ */
+public class PersistentMetadataValue extends MetadataValueAdapter implements MetadataValue {
+    /**
+     * Store the internal value that is represented by this value.
+     * This is expected to be one of a set of a valid serializable types.
+     */
+    private final Object internalValue;
+
+    /**
+     * Initializes a PersistentMetadataValue with an Object value.
+     * <p>
+     * The Object must be one of the valid persistable object types.
+     * Otherwise, an IllegalArgumentException will be thrown.
+     *
+     * @throws java.lang.IllegalArgumentException on non-persistable input
+     * @param owningPlugin the {@link org.bukkit.plugin.Plugin} that created this metadata value
+     * @param value the value assigned to this metadata value
+     */
+    public PersistentMetadataValue(Plugin owningPlugin, final Object value) {
+        super(owningPlugin);
+        this.internalValue = value;
+
+        if (!(
+              value instanceof ConfigurationSerializable
+           || value instanceof String
+           || value instanceof Integer
+           || value instanceof Double
+           || value instanceof Long
+           || value instanceof Boolean
+           || value instanceof Short
+           || value instanceof Float
+           || value instanceof Map
+           || value instanceof List
+        )) {
+            throw new IllegalArgumentException("Invalid Object type for PersistentMetadataValue: " + value.getClass());
+        }
+    }
+
+    @Override
+    public Object value() {
+        return internalValue;
+    }
+
+    @Override
+    public void invalidate() {
+
+    }
+}