001 package org.bukkit.inventory;
002
003 import org.bukkit.Color;
004 import org.bukkit.Material;
005 import org.bukkit.Server;
006 import org.bukkit.inventory.meta.BookMeta;
007 import org.bukkit.inventory.meta.ItemMeta;
008 import org.bukkit.inventory.meta.SkullMeta;
009
010 /**
011 * An instance of the ItemFactory can be obtained with {@link
012 * Server#getItemFactory()}.
013 * <p>
014 * The ItemFactory is solely responsible for creating item meta containers to
015 * apply on item stacks.
016 */
017 public interface ItemFactory {
018
019 /**
020 * This creates a new item meta for the material.
021 *
022 * @param material The material to consider as base for the meta
023 * @return a new ItemMeta that could be applied to an item stack of the
024 * specified material
025 */
026 ItemMeta getItemMeta(final Material material);
027
028 /**
029 * This method checks the item meta to confirm that it is applicable (no
030 * data lost if applied) to the specified ItemStack.
031 * <p>
032 * A {@link SkullMeta} would not be valid for a sword, but a normal {@link
033 * ItemMeta} from an enchanted dirt block would.
034 *
035 * @param meta Meta to check
036 * @param stack Item that meta will be applied to
037 * @return true if the meta can be applied without losing data, false
038 * otherwise
039 * @throws IllegalArgumentException if the meta was not created by this
040 * factory
041 */
042 boolean isApplicable(final ItemMeta meta, final ItemStack stack) throws IllegalArgumentException;
043
044 /**
045 * This method checks the item meta to confirm that it is applicable (no
046 * data lost if applied) to the specified Material.
047 * <p>
048 * A {@link SkullMeta} would not be valid for a sword, but a normal {@link
049 * ItemMeta} from an enchanted dirt block would.
050 *
051 * @param meta Meta to check
052 * @param material Material that meta will be applied to
053 * @return true if the meta can be applied without losing data, false
054 * otherwise
055 * @throws IllegalArgumentException if the meta was not created by this
056 * factory
057 */
058 boolean isApplicable(final ItemMeta meta, final Material material) throws IllegalArgumentException;
059
060 /**
061 * This method is used to compare two item meta data objects.
062 *
063 * @param meta1 First meta to compare, and may be null to indicate no data
064 * @param meta2 Second meta to compare, and may be null to indicate no
065 * data
066 * @return false if one of the meta has data the other does not, otherwise
067 * true
068 * @throws IllegalArgumentException if either meta was not created by this
069 * factory
070 */
071 boolean equals(final ItemMeta meta1, final ItemMeta meta2) throws IllegalArgumentException;
072
073 /**
074 * Returns an appropriate item meta for the specified stack.
075 * <p>
076 * The item meta returned will always be a valid meta for a given
077 * ItemStack of the specified material. It may be a more or less specific
078 * meta, and could also be the same meta or meta type as the parameter.
079 * The item meta returned will also always be the most appropriate meta.
080 * <p>
081 * Example, if a {@link SkullMeta} is being applied to a book, this method
082 * would return a {@link BookMeta} containing all information in the
083 * specified meta that is applicable to an {@link ItemMeta}, the highest
084 * common interface.
085 *
086 * @param meta the meta to convert
087 * @param stack the stack to convert the meta for
088 * @return An appropriate item meta for the specified item stack. No
089 * guarantees are made as to if a copy is returned. This will be null
090 * for a stack of air.
091 * @throws IllegalArgumentException if the specified meta was not created
092 * by this factory
093 */
094 ItemMeta asMetaFor(final ItemMeta meta, final ItemStack stack) throws IllegalArgumentException;
095
096 /**
097 * Returns an appropriate item meta for the specified material.
098 * <p>
099 * The item meta returned will always be a valid meta for a given
100 * ItemStack of the specified material. It may be a more or less specific
101 * meta, and could also be the same meta or meta type as the parameter.
102 * The item meta returned will also always be the most appropriate meta.
103 * <p>
104 * Example, if a {@link SkullMeta} is being applied to a book, this method
105 * would return a {@link BookMeta} containing all information in the
106 * specified meta that is applicable to an {@link ItemMeta}, the highest
107 * common interface.
108 *
109 * @param meta the meta to convert
110 * @param material the material to convert the meta for
111 * @return An appropriate item meta for the specified item material. No
112 * guarantees are made as to if a copy is returned. This will be null for air.
113 * @throws IllegalArgumentException if the specified meta was not created
114 * by this factory
115 */
116 ItemMeta asMetaFor(final ItemMeta meta, final Material material) throws IllegalArgumentException;
117
118 /**
119 * Returns the default color for all leather armor.
120 *
121 * @return the default color for leather armor
122 */
123 Color getDefaultLeatherColor();
124 }