SPIGOT-1916: Attribute modifiers for ItemStacks

By: Senmori <thesenmori@gmail.com>

paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java

@@ -1,11 +1,16 @@
 package org.bukkit.inventory.meta;
 
+import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
+import com.google.common.collect.Multimap;
+import org.bukkit.attribute.Attribute;
+import org.bukkit.attribute.AttributeModifier;
 import org.bukkit.configuration.serialization.ConfigurationSerializable;
 import org.bukkit.enchantments.Enchantment;
+import org.bukkit.inventory.EquipmentSlot;
 import org.bukkit.inventory.ItemFlag;
 
 /**
@@ -13,6 +18,8 @@ import org.bukkit.inventory.ItemFlag;
  * <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>
+ * <b>Attribute related APIs are draft API</b>
  */
 public interface ItemMeta extends Cloneable, ConfigurationSerializable {
 
@@ -194,6 +201,121 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable {
      */
     void setUnbreakable(boolean unbreakable);
 
+    /**
+     * Checks for the existence of any AttributeModifiers.
+     *
+     * @return true if any AttributeModifiers exist
+     */
+    boolean hasAttributeModifiers();
+
+    /**
+     * Return an immutable copy of all Attributes and
+     * their modifiers in this ItemMeta.<br>
+     * Returns null if none exist.
+     *
+     * @return an immutable {@link Multimap} of Attributes
+     *         and their AttributeModifiers, or null if none exist
+     */
+    Multimap<Attribute, AttributeModifier> getAttributeModifiers();
+
+    /**
+     * Return an immutable copy of all {@link Attribute}s and their
+     * {@link AttributeModifier}s for a given {@link EquipmentSlot}.<br>
+     * Any {@link AttributeModifier} that does have have a given
+     * {@link EquipmentSlot} will be returned. This is because
+     * AttributeModifiers without a slot are active in any slot.<br>
+     * If there are no attributes set for the given slot, an empty map
+     * will be returned.
+     *
+     * @param slot the {@link EquipmentSlot} to check
+     * @return the immutable {@link Multimap} with the
+     *         respective Attributes and modifiers, or an empty map
+     *         if no attributes are set.
+     */
+    Multimap<Attribute, AttributeModifier> getAttributeModifiers(EquipmentSlot slot);
+
+    /**
+     * Return an immutable copy of all {@link AttributeModifier}s
+     * for a given {@link Attribute}
+     *
+     * @param attribute the {@link Attribute}
+     * @return an immutable collection of {@link AttributeModifier}s
+     *          or null if no AttributeModifiers exist for the Attribute.
+     * @throws NullPointerException if Attribute is null
+     */
+    Collection<AttributeModifier> getAttributeModifiers(Attribute attribute);
+
+    /**
+     * Add an Attribute and it's Modifier.
+     * AttributeModifiers can now support {@link EquipmentSlot}s.
+     * If not set, the {@link AttributeModifier} will be active in ALL slots.
+     * <br>
+     * Two {@link AttributeModifier}s that have the same {@link java.util.UUID}
+     * cannot exist on the same Attribute.
+     *
+     * @param attribute the {@link Attribute} to modify
+     * @param modifier the {@link AttributeModifier} specifying the modification
+     * @return true if the Attribute and AttributeModifier were
+     *         successfully added
+     * @throws NullPointerException if Attribute is null
+     * @throws NullPointerException if AttributeModifier is null
+     * @throws IllegalArgumentException if AttributeModifier already exists
+     */
+    boolean addAttributeModifier(Attribute attribute, AttributeModifier modifier);
+
+    /**
+     * Set all {@link Attribute}s and their {@link AttributeModifier}s.
+     * To clear all currently set Attributes and AttributeModifiers use
+     * null or an empty Multimap.
+     * If not null nor empty, this will filter all entries that are not-null
+     * and add them to the ItemStack.
+     *
+     * @param attributeModifiers the new Multimap containing the Attributes
+     *                           and their AttributeModifiers
+     */
+    void setAttributeModifiers(Multimap<Attribute, AttributeModifier> attributeModifiers);
+
+    /**
+     * Remove all {@link AttributeModifier}s associated with the given
+     * {@link Attribute}.
+     * This will return false if nothing was removed.
+     *
+     * @param attribute attribute to remove
+     * @return  true if all modifiers were removed from a given
+     *                  Attribute. Returns false if no attributes were
+     *                  removed.
+     * @throws NullPointerException if Attribute is null
+     */
+    boolean removeAttributeModifier(Attribute attribute);
+
+    /**
+     * Remove all {@link Attribute}s and {@link AttributeModifier}s for a
+     * given {@link EquipmentSlot}.<br>
+     * If the given {@link EquipmentSlot} is null, this will remove all
+     * {@link AttributeModifier}s that do not have an EquipmentSlot set.
+     *
+     * @param slot the {@link EquipmentSlot} to clear all Attributes and
+     *             their modifiers for
+     * @return true if all modifiers were removed that match the given
+     *         EquipmentSlot.
+     */
+    boolean removeAttributeModifier(EquipmentSlot slot);
+
+    /**
+     * Remove a specific {@link Attribute} and {@link AttributeModifier}.
+     * AttributeModifiers are matched according to their {@link java.util.UUID}.
+     *
+     * @param attribute the {@link Attribute} to remove
+     * @param modifier the {@link AttributeModifier} to remove
+     * @return if any attribute modifiers were remove
+     *
+     * @see AttributeModifier#getUniqueId()
+     *
+     * @throws NullPointerException if the Attribute is null
+     * @throws NullPointerException if the AttributeModifier is null
+     */
+    boolean removeAttributeModifier(Attribute attribute, AttributeModifier modifier);
+
     @SuppressWarnings("javadoc")
     ItemMeta clone();
 }