001 package org.bukkit.plugin;
002
003 import java.io.File;
004 import java.io.InputStream;
005 import java.util.logging.Logger;
006
007 import org.bukkit.Server;
008 import org.bukkit.command.TabExecutor;
009 import org.bukkit.configuration.file.FileConfiguration;
010 import org.bukkit.generator.ChunkGenerator;
011
012 import com.avaje.ebean.EbeanServer;
013
014 /**
015 * Represents a Plugin
016 * <p>
017 * The use of {@link PluginBase} is recommended for actual Implementation
018 */
019 public interface Plugin extends TabExecutor {
020 /**
021 * Returns the folder that the plugin data's files are located in. The
022 * folder may not yet exist.
023 *
024 * @return The folder
025 */
026 public File getDataFolder();
027
028 /**
029 * Returns the plugin.yaml file containing the details for this plugin
030 *
031 * @return Contents of the plugin.yaml file
032 */
033 public PluginDescriptionFile getDescription();
034
035 /**
036 * Gets a {@link FileConfiguration} for this plugin, read through
037 * "config.yml"
038 * <p>
039 * If there is a default config.yml embedded in this plugin, it will be
040 * provided as a default for this Configuration.
041 *
042 * @return Plugin configuration
043 */
044 public FileConfiguration getConfig();
045
046 /**
047 * Gets an embedded resource in this plugin
048 *
049 * @param filename Filename of the resource
050 * @return File if found, otherwise null
051 */
052 public InputStream getResource(String filename);
053
054 /**
055 * Saves the {@link FileConfiguration} retrievable by {@link #getConfig()}.
056 */
057 public void saveConfig();
058
059 /**
060 * Saves the raw contents of the default config.yml file to the location
061 * retrievable by {@link #getConfig()}. If there is no default config.yml
062 * embedded in the plugin, an empty config.yml file is saved. This should
063 * fail silently if the config.yml already exists.
064 */
065 public void saveDefaultConfig();
066
067 /**
068 * Saves the raw contents of any resource embedded with a plugin's .jar
069 * file assuming it can be found using {@link #getResource(String)}.
070 * <p>
071 * The resource is saved into the plugin's data folder using the same
072 * hierarchy as the .jar file (subdirectories are preserved).
073 *
074 * @param resourcePath the embedded resource path to look for within the
075 * plugin's .jar file. (No preceding slash).
076 * @param replace if true, the embedded resource will overwrite the
077 * contents of an existing file.
078 * @throws IllegalArgumentException if the resource path is null, empty,
079 * or points to a nonexistent resource.
080 */
081 public void saveResource(String resourcePath, boolean replace);
082
083 /**
084 * Discards any data in {@link #getConfig()} and reloads from disk.
085 */
086 public void reloadConfig();
087
088 /**
089 * Gets the associated PluginLoader responsible for this plugin
090 *
091 * @return PluginLoader that controls this plugin
092 */
093 public PluginLoader getPluginLoader();
094
095 /**
096 * Returns the Server instance currently running this plugin
097 *
098 * @return Server running this plugin
099 */
100 public Server getServer();
101
102 /**
103 * Returns a value indicating whether or not this plugin is currently
104 * enabled
105 *
106 * @return true if this plugin is enabled, otherwise false
107 */
108 public boolean isEnabled();
109
110 /**
111 * Called when this plugin is disabled
112 */
113 public void onDisable();
114
115 /**
116 * Called after a plugin is loaded but before it has been enabled.
117 * <p>
118 * When mulitple plugins are loaded, the onLoad() for all plugins is
119 * called before any onEnable() is called.
120 */
121 public void onLoad();
122
123 /**
124 * Called when this plugin is enabled
125 */
126 public void onEnable();
127
128 /**
129 * Simple boolean if we can still nag to the logs about things
130 *
131 * @return boolean whether we can nag
132 */
133 public boolean isNaggable();
134
135 /**
136 * Set naggable state
137 *
138 * @param canNag is this plugin still naggable?
139 */
140 public void setNaggable(boolean canNag);
141
142 /**
143 * Gets the {@link EbeanServer} tied to this plugin. This will only be
144 * available if enabled in the {@link
145 * PluginDescriptionFile#isDatabaseEnabled()}
146 * <p>
147 * <i>For more information on the use of <a href="http://www.avaje.org/">
148 * Avaje Ebeans ORM</a>, see <a
149 * href="http://www.avaje.org/ebean/documentation.html">Avaje Ebeans
150 * Documentation</a></i>
151 * <p>
152 * <i>For an example using Ebeans ORM, see <a
153 * href="https://github.com/Bukkit/HomeBukkit">Bukkit's Homebukkit Plugin
154 * </a></i>
155 *
156 * @return ebean server instance or null if not enabled
157 */
158 public EbeanServer getDatabase();
159
160 /**
161 * Gets a {@link ChunkGenerator} for use in a default world, as specified
162 * in the server configuration
163 *
164 * @param worldName Name of the world that this will be applied to
165 * @param id Unique ID, if any, that was specified to indicate which
166 * generator was requested
167 * @return ChunkGenerator for use in the default world generation
168 */
169 public ChunkGenerator getDefaultWorldGenerator(String worldName, String id);
170
171 /**
172 * Returns the plugin logger associated with this server's logger. The
173 * returned logger automatically tags all log messages with the plugin's
174 * name.
175 *
176 * @return Logger associated with this plugin
177 */
178 public Logger getLogger();
179
180 /**
181 * Returns the name of the plugin.
182 * <p>
183 * This should return the bare name of the plugin and should be used for
184 * comparison.
185 *
186 * @return name of the plugin
187 */
188 public String getName();
189 }