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    }