diff options
Diffstat (limited to 'src/main/java/org/bukkit/inventory/meta')
-rw-r--r-- | src/main/java/org/bukkit/inventory/meta/ItemMeta.java | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java index 76d43266..73bdcebd 100644 --- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java +++ b/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(); } |