001    package org.bukkit.help;
002    
003    import java.util.Collection;
004    import java.util.List;
005    
006    /**
007     * The HelpMap tracks all help topics registered in a Bukkit server. When the
008     * server starts up or is reloaded, help is processed and topics are added in
009     * the following order:
010     * <p>
011     * <ol>
012     * <li>General topics are loaded from the help.yml
013     * <li>Plugins load and optionally call {@code addTopic()}
014     * <li>Registered plugin commands are processed by {@link HelpTopicFactory}
015     *     objects to create topics
016     * <li>Topic contents are amended as directed in help.yml
017     * </ol>
018     */
019    public interface HelpMap {
020        /**
021         * Returns a help topic for a given topic name.
022         *
023         * @param topicName The help topic name to look up.
024         * @return A {@link HelpTopic} object matching the topic name or null if
025         *     none can be found.
026         */
027        public HelpTopic getHelpTopic(String topicName);
028    
029        /**
030         * Returns a collection of all the registered help topics.
031         *
032         * @return All the registered help topics.
033         */
034        public Collection<HelpTopic> getHelpTopics();
035        
036        /**
037         * Adds a topic to the server's help index.
038         *
039         * @param topic The new help topic to add.
040         */
041        public void addTopic(HelpTopic topic);
042    
043        /**
044         * Clears out the contents of the help index. Normally called during
045         * server reload.
046         */
047        public void clear();
048    
049        /**
050         * Associates a {@link HelpTopicFactory} object with given command base
051         * class. Plugins typically call this method during {@code onLoad()}. Once
052         * registered, the custom HelpTopicFactory will be used to create a custom
053         * {@link HelpTopic} for all commands deriving from the {@code
054         * commandClass} base class, or all commands deriving from {@link
055         * org.bukkit.command.PluginCommand} who's executor derives from {@code
056         * commandClass} base class.
057         *
058         * @param commandClass The class for which the custom HelpTopicFactory
059         *     applies. Must derive from either {@link org.bukkit.command.Command}
060         *     or {@link org.bukkit.command.CommandExecutor}.
061         * @param factory The {@link HelpTopicFactory} implementation to associate
062         *     with the {@code commandClass}.
063         * @throws IllegalArgumentException Thrown if {@code commandClass} does
064         *     not derive from a legal base class.
065         */
066        public void registerHelpTopicFactory(Class<?> commandClass, HelpTopicFactory<?> factory);
067    
068        /**
069         * Gets the list of plugins the server administrator has chosen to exclude
070         * from the help index. Plugin authors who choose to directly extend
071         * {@link org.bukkit.command.Command} instead of {@link
072         * org.bukkit.command.PluginCommand} will need to check this collection in
073         * their {@link HelpTopicFactory} implementations to ensure they meet the
074         * server administrator's expectations.
075         *
076         * @return A list of plugins that should be excluded from the help index.
077         */
078        public List<String> getIgnoredPlugins();
079    }