001    package org.bukkit.metadata;
002    
003    import org.bukkit.plugin.Plugin;
004    
005    import java.util.List;
006    
007    /**
008     * This interface is implemented by all objects that can provide metadata
009     * about themselves.
010     */
011    public interface Metadatable {
012        /**
013         * Sets a metadata value in the implementing object's metadata store.
014         *
015         * @param metadataKey A unique key to identify this metadata.
016         * @param newMetadataValue The metadata value to apply.
017         * @throws IllegalArgumentException If value is null, or the owning plugin
018         *     is null
019         */
020        public void setMetadata(String metadataKey, MetadataValue newMetadataValue);
021    
022        /**
023         * Returns a list of previously set metadata values from the implementing
024         * object's metadata store.
025         *
026         * @param metadataKey the unique metadata key being sought.
027         * @return A list of values, one for each plugin that has set the
028         *     requested value.
029         */
030        public List<MetadataValue> getMetadata(String metadataKey);
031    
032        /**
033         * Tests to see whether the implementing object contains the given
034         * metadata value in its metadata store.
035         *
036         * @param metadataKey the unique metadata key being queried.
037         * @return the existence of the metadataKey within subject.
038         */
039        public boolean hasMetadata(String metadataKey);
040    
041        /**
042         * Removes the given metadata value from the implementing object's
043         * metadata store.
044         *
045         * @param metadataKey the unique metadata key identifying the metadata to
046         *     remove.
047         * @param owningPlugin This plugin's metadata value will be removed. All
048         *     other values will be left untouched.
049         * @throws IllegalArgumentException If plugin is null
050         */
051        public void removeMetadata(String metadataKey, Plugin owningPlugin);
052    }