001    package org.bukkit;
002    
003    import java.io.File;
004    import java.util.Iterator;
005    import java.util.List;
006    import java.util.Map;
007    import java.util.Set;
008    import java.util.UUID;
009    import java.util.logging.Logger;
010    
011    import org.bukkit.Warning.WarningState;
012    import org.bukkit.command.CommandException;
013    import org.bukkit.command.CommandSender;
014    import org.bukkit.command.ConsoleCommandSender;
015    import org.bukkit.command.PluginCommand;
016    import org.bukkit.entity.Player;
017    import org.bukkit.event.inventory.InventoryType;
018    import org.bukkit.help.HelpMap;
019    import org.bukkit.inventory.Inventory;
020    import org.bukkit.inventory.InventoryHolder;
021    import org.bukkit.inventory.ItemStack;
022    import org.bukkit.inventory.Recipe;
023    import org.bukkit.map.MapView;
024    import org.bukkit.plugin.PluginManager;
025    import org.bukkit.plugin.ServicesManager;
026    import org.bukkit.plugin.messaging.Messenger;
027    import org.bukkit.plugin.messaging.PluginMessageRecipient;
028    import org.bukkit.scheduler.BukkitScheduler;
029    import org.bukkit.scoreboard.ScoreboardManager;
030    
031    import com.avaje.ebean.config.ServerConfig;
032    import org.bukkit.inventory.ItemFactory;
033    import org.bukkit.inventory.meta.ItemMeta;
034    
035    /**
036     * Represents a server implementation
037     */
038    public interface Server extends PluginMessageRecipient {
039    
040        /**
041         * Used for all administrative messages, such as an operator using a command.
042         * <p>
043         * For use in {@link #broadcast(java.lang.String, java.lang.String)}
044         */
045        public static final String BROADCAST_CHANNEL_ADMINISTRATIVE = "bukkit.broadcast.admin";
046    
047        /**
048         * Used for all announcement messages, such as informing users that a player has joined.
049         * <p>
050         * For use in {@link #broadcast(java.lang.String, java.lang.String)}
051         */
052        public static final String BROADCAST_CHANNEL_USERS = "bukkit.broadcast.user";
053    
054        /**
055         * Gets the name of this server implementation
056         *
057         * @return name of this server implementation
058         */
059        public String getName();
060    
061        /**
062         * Gets the version string of this server implementation.
063         *
064         * @return version of this server implementation
065         */
066        public String getVersion();
067    
068        /**
069         * Gets the Bukkit version that this server is running.
070         *
071         * @return Version of Bukkit
072         */
073        public String getBukkitVersion();
074    
075        /**
076         * Gets a list of all currently logged in players
077         *
078         * @return An array of Players that are currently online
079         */
080        public Player[] getOnlinePlayers();
081    
082        /**
083         * Get the maximum amount of players which can login to this server
084         *
085         * @return The amount of players this server allows
086         */
087        public int getMaxPlayers();
088    
089        /**
090         * Get the game port that the server runs on
091         *
092         * @return The port number of this server
093         */
094        public int getPort();
095    
096        /**
097         * Get the view distance from this server.
098         *
099         * @return The view distance from this server.
100         */
101        public int getViewDistance();
102    
103        /**
104         * Get the IP that this server is bound to or empty string if not specified
105         *
106         * @return The IP string that this server is bound to, otherwise empty string
107         */
108        public String getIp();
109    
110        /**
111         * Get the name of this server
112         *
113         * @return The name of this server
114         */
115        public String getServerName();
116    
117        /**
118         * Get an ID of this server. The ID is a simple generally alphanumeric
119         * ID that can be used for uniquely identifying this server.
120         *
121         * @return The ID of this server
122         */
123        public String getServerId();
124    
125        /**
126         * Get world type (level-type setting) for default world
127         *
128         * @return The value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1)
129         */
130        public String getWorldType();
131    
132        /**
133         * Get generate-structures setting
134         *
135         * @return true if structure generation is enabled, false if not
136         */
137        public boolean getGenerateStructures();
138    
139        /**
140         * Gets whether this server allows the End or not.
141         *
142         * @return Whether this server allows the End or not.
143         */
144        public boolean getAllowEnd();
145    
146        /**
147         * Gets whether this server allows the Nether or not.
148         *
149         * @return Whether this server allows the Nether or not.
150         */
151        public boolean getAllowNether();
152    
153        /**
154         * Gets whether this server has a whitelist or not.
155         *
156         * @return Whether this server has a whitelist or not.
157         */
158        public boolean hasWhitelist();
159    
160        /**
161         * Sets the whitelist on or off
162         *
163         * @param value true if whitelist is on, otherwise false
164         */
165        public void setWhitelist(boolean value);
166    
167        /**
168         * Gets a list of whitelisted players
169         *
170         * @return Set containing all whitelisted players
171         */
172        public Set<OfflinePlayer> getWhitelistedPlayers();
173    
174        /**
175         * Reloads the whitelist from disk
176         */
177        public void reloadWhitelist();
178    
179        /**
180         * Broadcast a message to all players.
181         * <p>
182         * This is the same as calling {@link #broadcast(java.lang.String, java.lang.String)} to {@link #BROADCAST_CHANNEL_USERS}
183         *
184         * @param message the message
185         * @return the number of players
186         */
187        public int broadcastMessage(String message);
188    
189        /**
190         * Gets the name of the update folder. The update folder is used to safely update
191         * plugins at the right moment on a plugin load.
192         * <p>
193         * The update folder name is relative to the plugins folder.
194         *
195         * @return The name of the update folder
196         */
197        public String getUpdateFolder();
198    
199        /**
200         * Gets the update folder. The update folder is used to safely update
201         * plugins at the right moment on a plugin load.
202         *
203         * @return The name of the update folder
204         */
205        public File getUpdateFolderFile();
206    
207        /**
208         * Gets the value of the connection throttle setting
209         *
210         * @return the value of the connection throttle setting
211         */
212        public long getConnectionThrottle();
213    
214        /**
215         * Gets default ticks per animal spawns value
216         * <p>
217         * <b>Example Usage:</b>
218         * <ul>
219         * <li>A value of 1 will mean the server will attempt to spawn monsters every tick.
220         * <li>A value of 400 will mean the server will attempt to spawn monsters every 400th tick.
221         * <li>A value below 0 will be reset back to Minecraft's default.
222         * </ul>
223         * <p>
224         * <b>Note:</b>
225         * If set to 0, animal spawning will be disabled. We recommend using spawn-animals to control this instead.
226         * <p>
227         * Minecraft default: 400.
228         *
229         * @return The default ticks per animal spawns value
230         */
231        public int getTicksPerAnimalSpawns();
232    
233        /**
234         * Gets the default ticks per monster spawns value
235         * <p>
236         * <b>Example Usage:</b>
237         * <ul>
238         * <li>A value of 1 will mean the server will attempt to spawn monsters every tick.
239         * <li>A value of 400 will mean the server will attempt to spawn monsters every 400th tick.
240         * <li>A value below 0 will be reset back to Minecraft's default.
241         * </ul>
242         * <p>
243         * <b>Note:</b>
244         * If set to 0, monsters spawning will be disabled. We recommend using spawn-monsters to control this instead.
245         * <p>
246         * Minecraft default: 1.
247         *
248         * @return The default ticks per monsters spawn value
249         */
250        public int getTicksPerMonsterSpawns();
251    
252        /**
253         * Gets a player object by the given username
254         * <p>
255         * This method may not return objects for offline players
256         *
257         * @param name Name to look up
258         * @return Player if it was found, otherwise null
259         */
260        public Player getPlayer(String name);
261    
262        /**
263         * Gets the player with the exact given name, case insensitive
264         *
265         * @param name Exact name of the player to retrieve
266         * @return Player object or null if not found
267         */
268        public Player getPlayerExact(String name);
269    
270        /**
271         * Attempts to match any players with the given name, and returns a list
272         * of all possibly matches
273         * <p>
274         * This list is not sorted in any particular order. If an exact match is found,
275         * the returned list will only contain a single result.
276         *
277         * @param name Name to match
278         * @return List of all possible players
279         */
280        public List<Player> matchPlayer(String name);
281    
282        /**
283         * Gets the PluginManager for interfacing with plugins
284         *
285         * @return PluginManager for this Server instance
286         */
287        public PluginManager getPluginManager();
288    
289        /**
290         * Gets the Scheduler for managing scheduled events
291         *
292         * @return Scheduler for this Server instance
293         */
294        public BukkitScheduler getScheduler();
295    
296        /**
297         * Gets a services manager
298         *
299         * @return Services manager
300         */
301        public ServicesManager getServicesManager();
302    
303        /**
304         * Gets a list of all worlds on this server
305         *
306         * @return A list of worlds
307         */
308        public List<World> getWorlds();
309    
310        /**
311         * Creates or loads a world with the given name using the specified options.
312         * <p>
313         * If the world is already loaded, it will just return the equivalent of
314         * getWorld(creator.name()).
315         *
316         * @param creator The options to use when creating the world.
317         * @return Newly created or loaded world
318         */
319        public World createWorld(WorldCreator creator);
320    
321        /**
322         * Unloads a world with the given name.
323         *
324         * @param name Name of the world to unload
325         * @param save Whether to save the chunks before unloading.
326         * @return Whether the action was Successful
327         */
328        public boolean unloadWorld(String name, boolean save);
329    
330        /**
331         * Unloads the given world.
332         *
333         * @param world The world to unload
334         * @param save Whether to save the chunks before unloading.
335         * @return Whether the action was Successful
336         */
337        public boolean unloadWorld(World world, boolean save);
338    
339        /**
340         * Gets the world with the given name
341         *
342         * @param name Name of the world to retrieve
343         * @return World with the given name, or null if none exists
344         */
345        public World getWorld(String name);
346    
347        /**
348         * Gets the world from the given Unique ID
349         *
350         * @param uid Unique ID of the world to retrieve.
351         * @return World with the given Unique ID, or null if none exists.
352         */
353        public World getWorld(UUID uid);
354    
355        /**
356         * Gets the map from the given item ID.
357         *
358         * @param id ID of the map to get.
359         * @return The MapView if it exists, or null otherwise.
360         * @deprecated Magic value
361         */
362        @Deprecated
363        public MapView getMap(short id);
364    
365        /**
366         * Create a new map with an automatically assigned ID.
367         *
368         * @param world The world the map will belong to.
369         * @return The MapView just created.
370         */
371        public MapView createMap(World world);
372    
373        /**
374         * Reloads the server, refreshing settings and plugin information
375         */
376        public void reload();
377    
378        /**
379         * Returns the primary logger associated with this server instance
380         *
381         * @return Logger associated with this server
382         */
383        public Logger getLogger();
384    
385        /**
386         * Gets a {@link PluginCommand} with the given name or alias
387         *
388         * @param name Name of the command to retrieve
389         * @return PluginCommand if found, otherwise null
390         */
391        public PluginCommand getPluginCommand(String name);
392    
393        /**
394         * Writes loaded players to disk
395         */
396        public void savePlayers();
397    
398        /**
399         * Dispatches a command on the server, and executes it if found.
400         *
401         * @param sender The apparent sender of the command
402         * @param commandLine command + arguments. Example: "test abc 123"
403         * @return returns false if no target is found.
404         * @throws CommandException Thrown when the executor for the given command fails with an unhandled exception
405         */
406        public boolean dispatchCommand(CommandSender sender, String commandLine) throws CommandException;
407    
408        /**
409         * Populates a given {@link ServerConfig} with values attributes to this server
410         *
411         * @param config ServerConfig to populate
412         */
413        public void configureDbConfig(ServerConfig config);
414    
415        /**
416         * Adds a recipe to the crafting manager.
417         *
418         * @param recipe The recipe to add.
419         * @return True if the recipe was added, false if it wasn't for some reason.
420         */
421        public boolean addRecipe(Recipe recipe);
422    
423        /**
424         * Get a list of all recipes for a given item. The stack size is ignored in comparisons.
425         * If the durability is -1, it will match any data value.
426         *
427         * @param result The item whose recipes you want
428         * @return The list of recipes
429         */
430        public List<Recipe> getRecipesFor(ItemStack result);
431    
432        /**
433         * Get an iterator through the list of crafting recipes.
434         *
435         * @return The iterator.
436         */
437        public Iterator<Recipe> recipeIterator();
438    
439        /**
440         * Clears the list of crafting recipes.
441         */
442        public void clearRecipes();
443    
444        /**
445         * Resets the list of crafting recipes to the default.
446         */
447        public void resetRecipes();
448    
449        /**
450         * Gets a list of command aliases defined in the server properties.
451         *
452         * @return Map of aliases to command names
453         */
454        public Map<String, String[]> getCommandAliases();
455    
456        /**
457         * Gets the radius, in blocks, around each worlds spawn point to protect
458         *
459         * @return Spawn radius, or 0 if none
460         */
461        public int getSpawnRadius();
462    
463        /**
464         * Sets the radius, in blocks, around each worlds spawn point to protect
465         *
466         * @param value New spawn radius, or 0 if none
467         */
468        public void setSpawnRadius(int value);
469    
470        /**
471         * Gets whether the Server is in online mode or not.
472         *
473         * @return Whether the server is in online mode.
474         */
475        public boolean getOnlineMode();
476    
477        /**
478         * Gets whether this server allows flying or not.
479         *
480         * @return Whether this server allows flying or not.
481         */
482        public boolean getAllowFlight();
483    
484        /**
485         * Gets whether the server is in hardcore mode or not.
486         *
487         * @return Whether this server is in hardcore mode or not.
488         */
489        public boolean isHardcore();
490    
491        /**
492         * Gets whether to use vanilla (false) or exact behaviour (true).
493         *
494         * Vanilla behaviour: check for collisions and move the player if needed.
495         * Exact behaviour: spawn players exactly where they should be.
496         *
497         * @return Whether to use vanilla (false) or exact behaviour (true).
498         */
499        public boolean useExactLoginLocation();
500    
501        /**
502         * Shutdowns the server, stopping everything.
503         */
504        public void shutdown();
505    
506        /**
507         * Broadcasts the specified message to every user with the given permission
508         *
509         * @param message Message to broadcast
510         * @param permission Permission the users must have to receive the broadcast
511         * @return Amount of users who received the message
512         */
513        public int broadcast(String message, String permission);
514    
515        /**
516         * Gets the player by the given name, regardless if they are offline or online.
517         * <p>
518         * This will return an object even if the player does not exist. To this method, all players will exist.
519         *
520         * @param name Name of the player to retrieve
521         * @return OfflinePlayer object
522         */
523        public OfflinePlayer getOfflinePlayer(String name);
524    
525        /**
526         * Gets a set containing all current IPs that are banned
527         *
528         * @return Set containing banned IP addresses
529         */
530        public Set<String> getIPBans();
531    
532        /**
533         * Bans the specified address from the server
534         *
535         * @param address IP address to ban
536         */
537        public void banIP(String address);
538    
539        /**
540         * Unbans the specified address from the server
541         *
542         * @param address IP address to unban
543         */
544        public void unbanIP(String address);
545    
546        /**
547         * Gets a set containing all banned players
548         *
549         * @return Set containing banned players
550         */
551        public Set<OfflinePlayer> getBannedPlayers();
552    
553        /**
554         * Gets a set containing all player operators
555         *
556         * @return Set containing player operators
557         */
558        public Set<OfflinePlayer> getOperators();
559    
560        /**
561         * Gets the default {@link GameMode} for new players
562         *
563         * @return Default game mode
564         */
565        public GameMode getDefaultGameMode();
566    
567        /**
568         * Sets the default {@link GameMode} for new players
569         *
570         * @param mode New game mode
571         */
572        public void setDefaultGameMode(GameMode mode);
573    
574        /**
575         * Gets the {@link ConsoleCommandSender} that may be used as an input source
576         * for this server.
577         *
578         * @return The Console CommandSender
579         */
580        public ConsoleCommandSender getConsoleSender();
581    
582        /**
583         * Gets the folder that contains all of the various {@link World}s.
584         *
585         * @return World container folder
586         */
587        public File getWorldContainer();
588    
589        /**
590         * Gets every player that has ever played on this server.
591         *
592         * @return Array containing all players
593         */
594        public OfflinePlayer[] getOfflinePlayers();
595    
596        /**
597         * Gets the {@link Messenger} responsible for this server.
598         *
599         * @return Messenger responsible for this server.
600         */
601        public Messenger getMessenger();
602    
603        /**
604         * Gets the {@link HelpMap} providing help topics for this server.
605         *
606         * @return The server's HelpMap.
607         */
608        public HelpMap getHelpMap();
609    
610        /**
611         * Creates an empty inventory of the specified type. If the type is {@link InventoryType#CHEST},
612         * the new inventory has a size of 27; otherwise the new inventory has the normal size for
613         * its type.
614         *
615         * @param owner The holder of the inventory; can be null if there's no holder.
616         * @param type The type of inventory to create.
617         * @return The new inventory.
618         */
619        Inventory createInventory(InventoryHolder owner, InventoryType type);
620    
621        /**
622         * Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size.
623         *
624         * @param owner The holder of the inventory; can be null if there's no holder.
625         * @param size The size of inventory to create; must be a multiple of 9.
626         * @return The new inventory.
627         * @throws IllegalArgumentException If the size is not a multiple of 9.
628         */
629        Inventory createInventory(InventoryHolder owner, int size);
630    
631        /**
632         * Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size and title.
633         *
634         * @param owner The holder of the inventory; can be null if there's no holder.
635         * @param size The size of inventory to create; must be a multiple of 9.
636         * @param title The title of the inventory, to be displayed when it is viewed.
637         * @return The new inventory.
638         * @throws IllegalArgumentException If the size is not a multiple of 9.
639         */
640        Inventory createInventory(InventoryHolder owner, int size, String title);
641    
642        /**
643         * Gets user-specified limit for number of monsters that can spawn in a chunk
644         *
645         * @return The monster spawn limit
646         */
647        int getMonsterSpawnLimit();
648    
649        /**
650         * Gets user-specified limit for number of animals that can spawn in a chunk
651         *
652         * @return The animal spawn limit
653         */
654        int getAnimalSpawnLimit();
655    
656        /**
657         * Gets user-specified limit for number of water animals that can spawn in a chunk
658         *
659         * @return The water animal spawn limit
660         */
661        int getWaterAnimalSpawnLimit();
662    
663        /**
664         * Gets user-specified limit for number of ambient mobs that can spawn in a chunk
665         *
666         * @return The ambient spawn limit
667         */
668        int getAmbientSpawnLimit();
669    
670        /**
671         * Returns true if the current {@link Thread} is the server's primary thread
672         */
673        boolean isPrimaryThread();
674    
675        /**
676         * Gets the message that is displayed on the server list
677         *
678         * @return the servers MOTD
679         */
680        String getMotd();
681    
682        /**
683         * Gets the default message that is displayed when the server is stopped
684         *
685         * @return the shutdown message
686         */
687        String getShutdownMessage();
688    
689        /**
690         * Gets the current warning state for the server
691         *
692         * @return The configured WarningState
693         */
694        public WarningState getWarningState();
695    
696        /**
697         * Gets the instance of the item factory (for {@link ItemMeta}).
698         *
699         * @return the item factory
700         * @see ItemFactory
701         */
702        ItemFactory getItemFactory();
703    
704        /**
705         * Gets the instance of the scoreboard manager.
706         * <p>
707         * This will only exist after the first world has loaded.
708         *
709         * @return the scoreboard manager or null if no worlds are loaded.
710         */
711        ScoreboardManager getScoreboardManager();
712    }