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