[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,36 @@ private boolean setItemMeta0(ItemMeta itemMeta, Material material) {
 
         return true;
     }
+
+    /**
+     * This may provide a more efficient 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.
+     *
+     * @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 may provide a more efficient 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.
+     *
+     * @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,42 @@ 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);
+
+    /**
+     * Set a MetadataValue for a given key.
+     *
+     * @param metadataKey A unique key to identify this metadata.
+     * @param newMetadataValue The metadata value to apply.
+     */
+    public void setMetadata(String metadataKey, MetadataValue newMetadataValue);
+
     /**
      * Checks for the existence of any enchantments.
      *
@@ -124,6 +167,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,175 @@
+package org.bukkit.metadata;
+
+import org.bukkit.configuration.serialization.ConfigurationSerializable;
+import org.bukkit.plugin.Plugin;
+
+import java.util.Collections;
+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 a
+     * ConfigurationSerializable Object
+     *
+     * @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 ConfigurationSerializable value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a String value.
+     *
+     * @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 String value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with an Integer value.
+     *
+     * @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 Integer value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a Boolean value.
+     *
+     * @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 Boolean value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a Long value.
+     *
+     * @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 Long value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a Double value.
+     *
+     * @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 Double value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a Short value.
+     *
+     * @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 Short value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a Byte value.
+     *
+     * @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 Byte value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a Float value.
+     *
+     * @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 Float value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a List value.
+     * <p>
+     * Note that the contents of the List must also be persistable,
+     * otherwise an IllegalArgumentException may be generated when
+     * the metadata store persists.
+     *
+     * @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 List<?> value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with a Map value.
+     * <p>
+     * Note that the keys of the Map must be Strings, and the
+     * contents of the Map must be persistable,
+     * otherwise an IllegalArgumentException may be generated when
+     * the metadata store persists.
+     *
+     * @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 Map<String, ?> value) {
+        this(owningPlugin, (Object)value);
+    }
+
+    /**
+     * Initializes a PersistentMetadataValue with an Object value.
+     * <p>
+     * The Object must be one of the valid persistable object types.
+     *
+     * @param owningPlugin the {@link org.bukkit.plugin.Plugin} that created this metadata value
+     * @param value the value assigned to this metadata value
+     */
+    private PersistentMetadataValue(Plugin owningPlugin, final Object value) {
+        super(owningPlugin);
+        this.internalValue = value;
+    }
+
+    @Override
+    public Object value() {
+        return internalValue;
+    }
+
+    @Override
+    public void invalidate() {
+
+    }
+
+    public List<Object> asList() {
+        return internalValue instanceof List ? (List<Object>)internalValue : Collections.emptyList();
+    }
+
+    public Map<String, Object> asMap() {
+        return internalValue instanceof Map ? (Map<String, Object>)internalValue : Collections.<String, Object>emptyMap();
+    }
+}