001    package org.bukkit.metadata;
002    
003    import org.bukkit.plugin.Plugin;
004    
005    import java.util.List;
006    
007    public interface MetadataStore<T> {
008        /**
009         * Adds a metadata value to an object.
010         *
011         * @param subject The object receiving the metadata.
012         * @param metadataKey A unique key to identify this metadata.
013         * @param newMetadataValue The metadata value to apply.
014         * @throws IllegalArgumentException If value is null, or the owning plugin
015         *     is null
016         */
017        public void setMetadata(T subject, String metadataKey, MetadataValue newMetadataValue);
018    
019        /**
020         * Returns all metadata values attached to an object. If multiple plugins
021         * have attached metadata, each will value will be included.
022         *
023         * @param subject the object being interrogated.
024         * @param metadataKey the unique metadata key being sought.
025         * @return A list of values, one for each plugin that has set the
026         *     requested value.
027         */
028        public List<MetadataValue> getMetadata(T subject, String metadataKey);
029    
030        /**
031         * Tests to see if a metadata attribute has been set on an object.
032         *
033         * @param subject the object upon which the has-metadata test is
034         *     performed.
035         * @param metadataKey the unique metadata key being queried.
036         * @return the existence of the metadataKey within subject.
037         */
038        public boolean hasMetadata(T subject, String metadataKey);
039    
040        /**
041         * Removes a metadata item owned by a plugin from a subject.
042         *
043         * @param subject the object to remove the metadata from.
044         * @param metadataKey the unique metadata key identifying the metadata to
045         *     remove.
046         * @param owningPlugin the plugin attempting to remove a metadata item.
047         * @throws IllegalArgumentException If plugin is null
048         */
049        public void removeMetadata(T subject, String metadataKey, Plugin owningPlugin);
050    
051        /**
052         * Invalidates all metadata in the metadata store that originates from the
053         * given plugin. Doing this will force each invalidated metadata item to
054         * be recalculated the next time it is accessed.
055         *
056         * @param owningPlugin the plugin requesting the invalidation.
057         * @throws IllegalArgumentException If plugin is null
058         */
059        public void invalidateAll(Plugin owningPlugin);
060    }