Upstream/Paper
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-12-29 04:17:44 +01:00
Code Issues Projects Releases Wiki Activity

SPIGOT-2540: Add nullability annotations to entire Bukkit API

Browse Source 
By: Darkyenus <darkyenus@gmail.com>
This commit is contained in:
Bukkit/Spigot 2019-03-13 17:42:57 +11:00
parent e069a80fd8
commit 416c865476
565 changed files with 5372 additions and 2008 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
paper-api/README.md
View File

@ -19,7 +19,7 @@ Bukkit is a Java program which uses [Maven 3](http://maven.apache.org/) for comp
* Install Maven and Git using your preferred installation methods.
* `git clone https://hub.spigotmc.org/stash/scm/spigot/bukkit.git`.
* `mvn clean install`.
* `mvn -P development clean install`.
Some IDEs such as [NetBeans](https://netbeans.org/) can perform these steps for you. Any Maven capable Java IDE can be used to develop with Bukkit, however the current team's personal preference is to use NetBeans.
@ -68,6 +68,7 @@ Code Requirements
* All major additions should have documentation(e.g. javadocs).
* Try to follow test driven development where available.
* All code should be free of magic values. If this is not possible, it should be marked with a TODO comment indicating it should be addressed in the future.
* All non-private methods and constructors must have specified nullability through [annotations](https://github.com/JetBrains/java-annotations)
Bukkit/CraftBukkit employs [JUnit 4](http://www.vogella.com/articles/JUnit/article.html) for testing. Pull Requests(PR) should attempt to integrate within that framework as appropriate.
Bukkit is a large project and what seems simple to a PR author at the time of writing may easily be overlooked by other authors and updates. Including unit tests with your PR

13
paper-api/pom.xml
View File

@ -83,6 +83,13 @@
<version>1.23</version>
<scope>compile</scope>
</dependency>
<!-- annotations -->
<dependency>
<groupId>org.jetbrains</groupId>
<artifactId>annotations-java5</artifactId>
<version>17.0.0</version>
<scope>provided</scope>
</dependency>
<!-- testing -->
<dependency>
<groupId>junit</groupId>
@ -96,6 +103,12 @@
<version>1.3</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.ow2.asm</groupId>
<artifactId>asm-tree</artifactId>
<version>7.1</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>

5
paper-api/src/main/java/org/bukkit/Achievement.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.Nullable;
/**
* Represents an achievement, which may be given to players.
* @deprecated future versions of Minecraft do not have achievements
@ -48,7 +50,7 @@ public enum Achievement {
parent = null;
}
private Achievement(Achievement parent) {
private Achievement(@Nullable Achievement parent) {
this.parent = parent;
}
@ -66,6 +68,7 @@ public enum Achievement {
*
* @return the parent achievement or null
*/
@Nullable
public Achievement getParent() {
return parent;
}

6
paper-api/src/main/java/org/bukkit/Art.java
View File

@ -5,6 +5,8 @@ import java.util.HashMap;
import org.apache.commons.lang.Validate;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents the art on a painting
@ -84,6 +86,7 @@ public enum Art {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static Art getById(int id) {
return BY_ID.get(id);
}
@ -96,7 +99,8 @@ public enum Art {
* @param name The name
* @return The painting
*/
public static Art getByName(String name) {
@Nullable
public static Art getByName(@NotNull String name) {
Validate.notNull(name, "Name cannot be null");
return BY_NAME.get(name.toLowerCase(java.util.Locale.ENGLISH));

16
paper-api/src/main/java/org/bukkit/BanEntry.java
View File

@ -1,5 +1,8 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.Date;
/**
@ -47,6 +50,7 @@ public interface BanEntry {
*
* @return the target name or IP address
*/
@NotNull
public String getTarget();
/**
@ -54,6 +58,7 @@ public interface BanEntry {
*
* @return the creation date
*/
@NotNull
public Date getCreated();
/**
@ -62,7 +67,7 @@ public interface BanEntry {
* @param created the new created date, cannot be null
* @see #save() saving changes
*/
public void setCreated(Date created);
public void setCreated(@NotNull Date created);
/**
* Gets the source of this ban.
@ -72,6 +77,7 @@ public interface BanEntry {
*
* @return the source of the ban
*/
@NotNull
public String getSource();
/**
@ -83,13 +89,14 @@ public interface BanEntry {
* @param source the new source where null values become empty strings
* @see #save() saving changes
*/
public void setSource(String source);
public void setSource(@NotNull String source);
/**
* Gets the date this ban expires on, or null for no defined end date.
*
* @return the expiration date
*/
@Nullable
public Date getExpiration();
/**
@ -100,13 +107,14 @@ public interface BanEntry {
* eternity
* @see #save() saving changes
*/
public void setExpiration(Date expiration);
public void setExpiration(@Nullable Date expiration);
/**
* Gets the reason for this ban.
*
* @return the ban reason, or null if not set
*/
@Nullable
public String getReason();
/**
@ -116,7 +124,7 @@ public interface BanEntry {
* default
* @see #save() saving changes
*/
public void setReason(String reason);
public void setReason(@Nullable String reason);
/**
* Saves the ban entry, overwriting any previous data in the ban list.

14
paper-api/src/main/java/org/bukkit/BanList.java
View File

@ -1,5 +1,8 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.Date;
import java.util.Set;
@ -29,7 +32,8 @@ public interface BanList {
* @param target entry parameter to search for
* @return the corresponding entry, or null if none found
*/
public BanEntry getBanEntry(String target);
@Nullable
public BanEntry getBanEntry(@NotNull String target);
/**
* Adds a ban to the this list. If a previous ban exists, this will
@ -43,13 +47,15 @@ public interface BanList {
* @return the entry for the newly created ban, or the entry for the
* (updated) previous ban
*/
public BanEntry addBan(String target, String reason, Date expires, String source);
@Nullable
public BanEntry addBan(@NotNull String target, @Nullable String reason, @Nullable Date expires, @Nullable String source);
/**
* Gets a set containing every {@link BanEntry} in this list.
*
* @return an immutable set containing every entry tracked by this list
*/
@NotNull
public Set<BanEntry> getBanEntries();
/**
@ -60,7 +66,7 @@ public interface BanList {
* @return true if a {@link BanEntry} exists for the name, indicating an
* active ban status, false otherwise
*/
public boolean isBanned(String target);
public boolean isBanned(@NotNull String target);
/**
* Removes the specified target from this list, therefore indicating a
@ -68,5 +74,5 @@ public interface BanList {
*
* @param target the target to remove from this list
*/
public void pardon(String target);
public void pardon(@NotNull String target);
}

4
paper-api/src/main/java/org/bukkit/BlockChangeDelegate.java
View File

@ -1,6 +1,7 @@
package org.bukkit;
import org.bukkit.block.data.BlockData;
import org.jetbrains.annotations.NotNull;
/**
* A delegate for handling block changes. This serves as a direct interface
@ -18,7 +19,7 @@ public interface BlockChangeDelegate {
* @param blockData Block data
* @return true if the block was set successfully
*/
public boolean setBlockData(int x, int y, int z, BlockData blockData);
public boolean setBlockData(int x, int y, int z, @NotNull BlockData blockData);
/**
* Get the block data at the location.
@ -28,6 +29,7 @@ public interface BlockChangeDelegate {
* @param z Z coordinate
* @return The block data
*/
@NotNull
public BlockData getBlockData(int x, int y, int z);
/**

173
paper-api/src/main/java/org/bukkit/Bukkit.java
View File

@ -50,6 +50,9 @@ import org.bukkit.generator.ChunkGenerator;
import org.bukkit.inventory.ItemFactory;
import org.bukkit.inventory.meta.ItemMeta;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents the Bukkit core, for version and Server singleton handling
@ -67,6 +70,7 @@ public final class Bukkit {
*
* @return Server instance being ran
*/
@NotNull
public static Server getServer() {
return server;
}
@ -78,7 +82,7 @@ public final class Bukkit {
*
* @param server Server instance
*/
public static void setServer(Server server) {
public static void setServer(@NotNull Server server) {
if (Bukkit.server != null) {
throw new UnsupportedOperationException("Cannot redefine singleton Server");
}
@ -92,6 +96,7 @@ public final class Bukkit {
*
* @return name of this server implementation
*/
@NotNull
public static String getName() {
return server.getName();
}
@ -101,6 +106,7 @@ public final class Bukkit {
*
* @return version of this server implementation
*/
@NotNull
public static String getVersion() {
return server.getVersion();
}
@ -110,6 +116,7 @@ public final class Bukkit {
*
* @return version of Bukkit
*/
@NotNull
public static String getBukkitVersion() {
return server.getBukkitVersion();
}
@ -141,6 +148,7 @@ public final class Bukkit {
*
* @return a view of currently online players.
*/
@NotNull
public static Collection<? extends Player> getOnlinePlayers() {
return server.getOnlinePlayers();
}
@ -179,6 +187,7 @@ public final class Bukkit {
* @return the IP string that this server is bound to, otherwise empty
* string
*/
@NotNull
public static String getIp() {
return server.getIp();
}
@ -190,6 +199,7 @@ public final class Bukkit {
* @deprecated not a standard server property
*/
@Deprecated
@NotNull
public static String getServerName() {
return server.getServerName();
}
@ -202,6 +212,7 @@ public final class Bukkit {
* @deprecated not a standard server property
*/
@Deprecated
@NotNull
public static String getServerId() {
return server.getServerId();
}
@ -211,6 +222,7 @@ public final class Bukkit {
*
* @return the value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1)
*/
@NotNull
public static String getWorldType() {
return server.getWorldType();
}
@ -265,6 +277,7 @@ public final class Bukkit {
*
* @return a set containing all whitelisted players
*/
@NotNull
public static Set<OfflinePlayer> getWhitelistedPlayers() {
return server.getWhitelistedPlayers();
}
@ -285,7 +298,7 @@ public final class Bukkit {
* @param message the message
* @return the number of players
*/
public static int broadcastMessage(String message) {
public static int broadcastMessage(@NotNull String message) {
return server.broadcastMessage(message);
}
@ -297,6 +310,7 @@ public final class Bukkit {
*
* @return the name of the update folder
*/
@NotNull
public static String getUpdateFolder() {
return server.getUpdateFolder();
}
@ -307,6 +321,7 @@ public final class Bukkit {
*
* @return the update folder
*/
@NotNull
public static File getUpdateFolderFile() {
return server.getUpdateFolderFile();
}
@ -377,7 +392,8 @@ public final class Bukkit {
* @return a player if one was found, null otherwise
*/
@Deprecated
public static Player getPlayer(String name) {
@Nullable
public static Player getPlayer(@NotNull String name) {
return server.getPlayer(name);
}
@ -390,7 +406,8 @@ public final class Bukkit {
* @return a player object if one was found, null otherwise
*/
@Deprecated
public static Player getPlayerExact(String name) {
@Nullable
public static Player getPlayerExact(@NotNull String name) {
return server.getPlayerExact(name);
}
@ -407,7 +424,8 @@ public final class Bukkit {
* @return list of all possible players
*/
@Deprecated
public static List<Player> matchPlayer(String name) {
@NotNull
public static List<Player> matchPlayer(@NotNull String name) {
return server.matchPlayer(name);
}
@ -417,7 +435,8 @@ public final class Bukkit {
* @param id UUID of the player to retrieve
* @return a player object if one was found, null otherwise
*/
public static Player getPlayer(UUID id) {
@Nullable
public static Player getPlayer(@NotNull UUID id) {
return server.getPlayer(id);
}
@ -426,6 +445,7 @@ public final class Bukkit {
*
* @return a plugin manager for this Server instance
*/
@NotNull
public static PluginManager getPluginManager() {
return server.getPluginManager();
}
@ -435,6 +455,7 @@ public final class Bukkit {
*
* @return a scheduling service for this server
*/
@NotNull
public static BukkitScheduler getScheduler() {
return server.getScheduler();
}
@ -444,6 +465,7 @@ public final class Bukkit {
*
* @return s services manager
*/
@NotNull
public static ServicesManager getServicesManager() {
return server.getServicesManager();
}
@ -453,6 +475,7 @@ public final class Bukkit {
*
* @return a list of worlds
*/
@NotNull
public static List<World> getWorlds() {
return server.getWorlds();
}
@ -467,7 +490,8 @@ public final class Bukkit {
* @param creator the options to use when creating the world
* @return newly created or loaded world
*/
public static World createWorld(WorldCreator creator) {
@Nullable
public static World createWorld(@NotNull WorldCreator creator) {
return server.createWorld(creator);
}
@ -478,7 +502,7 @@ public final class Bukkit {
* @param save whether to save the chunks before unloading
* @return true if successful, false otherwise
*/
public static boolean unloadWorld(String name, boolean save) {
public static boolean unloadWorld(@NotNull String name, boolean save) {
return server.unloadWorld(name, save);
}
@ -489,7 +513,7 @@ public final class Bukkit {
* @param save whether to save the chunks before unloading
* @return true if successful, false otherwise
*/
public static boolean unloadWorld(World world, boolean save) {
public static boolean unloadWorld(@NotNull World world, boolean save) {
return server.unloadWorld(world, save);
}
@ -499,7 +523,8 @@ public final class Bukkit {
* @param name the name of the world to retrieve
* @return a world with the given name, or null if none exists
*/
public static World getWorld(String name) {
@Nullable
public static World getWorld(@NotNull String name) {
return server.getWorld(name);
}
@ -509,7 +534,8 @@ public final class Bukkit {
* @param uid a unique-id of the world to retrieve
* @return a world with the given Unique ID, or null if none exists
*/
public static World getWorld(UUID uid) {
@Nullable
public static World getWorld(@NotNull UUID uid) {
return server.getWorld(uid);
}
@ -521,6 +547,7 @@ public final class Bukkit {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static MapView getMap(int id) {
return server.getMap(id);
}
@ -531,7 +558,8 @@ public final class Bukkit {
* @param world the world the map will belong to
* @return a newly created map view
*/
public static MapView createMap(World world) {
@NotNull
public static MapView createMap(@NotNull World world) {
return server.createMap(world);
}
@ -550,7 +578,8 @@ public final class Bukkit {
* @see World#locateNearestStructure(org.bukkit.Location,
* org.bukkit.StructureType, int, boolean)
*/
public static ItemStack createExplorerMap(World world, Location location, StructureType structureType) {
@NotNull
public static ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType) {
return server.createExplorerMap(world, location, structureType);
}
@ -572,7 +601,8 @@ public final class Bukkit {
* @see World#locateNearestStructure(org.bukkit.Location,
* org.bukkit.StructureType, int, boolean)
*/
public static ItemStack createExplorerMap(World world, Location location, StructureType structureType, int radius, boolean findUnexplored) {
@NotNull
public static ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType, int radius, boolean findUnexplored) {
return server.createExplorerMap(world, location, structureType, radius, findUnexplored);
}
@ -596,6 +626,7 @@ public final class Bukkit {
*
* @return Logger associated with this server
*/
@NotNull
public static Logger getLogger() {
return server.getLogger();
}
@ -606,7 +637,8 @@ public final class Bukkit {
* @param name the name of the command to retrieve
* @return a plugin command if found, null otherwise
*/
public static PluginCommand getPluginCommand(String name) {
@Nullable
public static PluginCommand getPluginCommand(@NotNull String name) {
return server.getPluginCommand(name);
}
@ -627,7 +659,7 @@ public final class Bukkit {
* @throws CommandException thrown when the executor for the given command
* fails with an unhandled exception
*/
public static boolean dispatchCommand(CommandSender sender, String commandLine) throws CommandException {
public static boolean dispatchCommand(@NotNull CommandSender sender, @NotNull String commandLine) throws CommandException {
return server.dispatchCommand(sender, commandLine);
}
@ -638,7 +670,8 @@ public final class Bukkit {
* @return true if the recipe was added, false if it wasn't for some
* reason
*/
public static boolean addRecipe(Recipe recipe) {
@Contract("null -> false")
public static boolean addRecipe(@Nullable Recipe recipe) {
return server.addRecipe(recipe);
}
@ -649,7 +682,8 @@ public final class Bukkit {
* @param result the item to match against recipe results
* @return a list of recipes with the given result
*/
public static List<Recipe> getRecipesFor(ItemStack result) {
@NotNull
public static List<Recipe> getRecipesFor(@NotNull ItemStack result) {
return server.getRecipesFor(result);
}
@ -658,6 +692,7 @@ public final class Bukkit {
*
* @return an iterator
*/
@NotNull
public static Iterator<Recipe> recipeIterator() {
return server.recipeIterator();
}
@ -681,6 +716,7 @@ public final class Bukkit {
*
* @return a map of aliases to command names
*/
@NotNull
public static Map<String, String[]> getCommandAliases() {
return server.getCommandAliases();
}
@ -746,7 +782,7 @@ public final class Bukkit {
* permissibles} must have to receive the broadcast
* @return number of message recipients
*/
public static int broadcast(String message, String permission) {
public static int broadcast(@NotNull String message, @NotNull String permission) {
return server.broadcast(message, permission);
}
@ -767,7 +803,8 @@ public final class Bukkit {
* @see #getOfflinePlayer(java.util.UUID)
*/
@Deprecated
public static OfflinePlayer getOfflinePlayer(String name) {
@NotNull
public static OfflinePlayer getOfflinePlayer(@NotNull String name) {
return server.getOfflinePlayer(name);
}
@ -781,7 +818,8 @@ public final class Bukkit {
* @param id the UUID of the player to retrieve
* @return an offline player
*/
public static OfflinePlayer getOfflinePlayer(UUID id) {
@NotNull
public static OfflinePlayer getOfflinePlayer(@NotNull UUID id) {
return server.getOfflinePlayer(id);
}
@ -790,6 +828,7 @@ public final class Bukkit {
*
* @return a set containing banned IP addresses
*/
@NotNull
public static Set<String> getIPBans() {
return server.getIPBans();
}
@ -799,7 +838,7 @@ public final class Bukkit {
*
* @param address the IP address to ban
*/
public static void banIP(String address) {
public static void banIP(@NotNull String address) {
server.banIP(address);
}
@ -808,7 +847,7 @@ public final class Bukkit {
*
* @param address the IP address to unban
*/
public static void unbanIP(String address) {
public static void unbanIP(@NotNull String address) {
server.unbanIP(address);
}
@ -817,6 +856,7 @@ public final class Bukkit {
*
* @return a set containing banned players
*/
@NotNull
public static Set<OfflinePlayer> getBannedPlayers() {
return server.getBannedPlayers();
}
@ -830,7 +870,8 @@ public final class Bukkit {
* @param type the type of list to fetch, cannot be null
* @return a ban list of the specified type
*/
public static BanList getBanList(BanList.Type type) {
@NotNull
public static BanList getBanList(@NotNull BanList.Type type) {
return server.getBanList(type);
}
@ -839,6 +880,7 @@ public final class Bukkit {
*
* @return a set containing player operators
*/
@NotNull
public static Set<OfflinePlayer> getOperators() {
return server.getOperators();
}
@ -848,6 +890,7 @@ public final class Bukkit {
*
* @return the default game mode
*/
@NotNull
public static GameMode getDefaultGameMode() {
return server.getDefaultGameMode();
}
@ -857,7 +900,7 @@ public final class Bukkit {
*
* @param mode the new game mode
*/
public static void setDefaultGameMode(GameMode mode) {
public static void setDefaultGameMode(@NotNull GameMode mode) {
server.setDefaultGameMode(mode);
}
@ -867,6 +910,7 @@ public final class Bukkit {
*
* @return a console command sender
*/
@NotNull
public static ConsoleCommandSender getConsoleSender() {
return server.getConsoleSender();
}
@ -876,6 +920,7 @@ public final class Bukkit {
*
* @return folder that contains all worlds
*/
@NotNull
public static File getWorldContainer() {
return server.getWorldContainer();
}
@ -885,6 +930,7 @@ public final class Bukkit {
*
* @return an array containing all previous players
*/
@NotNull
public static OfflinePlayer[] getOfflinePlayers() {
return server.getOfflinePlayers();
}
@ -894,6 +940,7 @@ public final class Bukkit {
*
* @return messenger responsible for this server
*/
@NotNull
public static Messenger getMessenger() {
return server.getMessenger();
}
@ -903,6 +950,7 @@ public final class Bukkit {
*
* @return a help map for this server
*/
@NotNull
public static HelpMap getHelpMap() {
return server.getHelpMap();
}
@ -930,7 +978,8 @@ public final class Bukkit {
*
* @see InventoryType#isCreatable()
*/
public static Inventory createInventory(InventoryHolder owner, InventoryType type) {
@NotNull
public static Inventory createInventory(@Nullable InventoryHolder owner, @NotNull InventoryType type) {
return server.createInventory(owner, type);
}
@ -958,7 +1007,8 @@ public final class Bukkit {
*
* @see InventoryType#isCreatable()
*/
public static Inventory createInventory(InventoryHolder owner, InventoryType type, String title) {
@NotNull
public static Inventory createInventory(@Nullable InventoryHolder owner, @NotNull InventoryType type, @NotNull String title) {
return server.createInventory(owner, type, title);
}
@ -971,7 +1021,8 @@ public final class Bukkit {
* @return a new inventory
* @throws IllegalArgumentException if the size is not a multiple of 9
*/
public static Inventory createInventory(InventoryHolder owner, int size) throws IllegalArgumentException {
@NotNull
public static Inventory createInventory(@Nullable InventoryHolder owner, int size) throws IllegalArgumentException {
return server.createInventory(owner, size);
}
@ -986,7 +1037,8 @@ public final class Bukkit {
* @return a new inventory
* @throws IllegalArgumentException if the size is not a multiple of 9
*/
public static Inventory createInventory(InventoryHolder owner, int size, String title) throws IllegalArgumentException {
@NotNull
public static Inventory createInventory(@Nullable InventoryHolder owner, int size, @NotNull String title) throws IllegalArgumentException {
return server.createInventory(owner, size, title);
}
@ -997,7 +1049,8 @@ public final class Bukkit {
* when the merchant inventory is viewed
* @return a new merchant
*/
public static Merchant createMerchant(String title) {
@NotNull
public static Merchant createMerchant(@Nullable String title) {
return server.createMerchant(title);
}
@ -1062,6 +1115,7 @@ public final class Bukkit {
*
* @return the servers MOTD
*/
@NotNull
public static String getMotd() {
return server.getMotd();
}
@ -1071,6 +1125,7 @@ public final class Bukkit {
*
* @return the shutdown message
*/
@Nullable
public static String getShutdownMessage() {
return server.getShutdownMessage();
}
@ -1080,6 +1135,7 @@ public final class Bukkit {
*
* @return the configured warning state
*/
@NotNull
public static WarningState getWarningState() {
return server.getWarningState();
}
@ -1090,6 +1146,7 @@ public final class Bukkit {
* @return the item factory
* @see ItemFactory
*/
@NotNull
public static ItemFactory getItemFactory() {
return server.getItemFactory();
}
@ -1101,6 +1158,7 @@ public final class Bukkit {
*
* @return the scoreboard manager or null if no worlds are loaded.
*/
@Nullable
public static ScoreboardManager getScoreboardManager() {
return server.getScoreboardManager();
}
@ -1112,6 +1170,7 @@ public final class Bukkit {
* implementation to indicate no defined icon, but this behavior is
* not guaranteed
*/
@Nullable
public static CachedServerIcon getServerIcon() {
return server.getServerIcon();
}
@ -1130,7 +1189,8 @@ public final class Bukkit {
* @return a cached server-icon that can be used for a {@link
* ServerListPingEvent#setServerIcon(CachedServerIcon)}
*/
public static CachedServerIcon loadServerIcon(File file) throws IllegalArgumentException, Exception {
@NotNull
public static CachedServerIcon loadServerIcon(@NotNull File file) throws IllegalArgumentException, Exception {
return server.loadServerIcon(file);
}
@ -1147,7 +1207,8 @@ public final class Bukkit {
* @return a cached server-icon that can be used for a {@link
* ServerListPingEvent#setServerIcon(CachedServerIcon)}
*/
public static CachedServerIcon loadServerIcon(BufferedImage image) throws IllegalArgumentException, Exception {
@NotNull
public static CachedServerIcon loadServerIcon(@NotNull BufferedImage image) throws IllegalArgumentException, Exception {
return server.loadServerIcon(image);
}
@ -1181,7 +1242,8 @@ public final class Bukkit {
* @return a new ChunkData for the world
*
*/
public static ChunkGenerator.ChunkData createChunkData(World world) {
@NotNull
public static ChunkGenerator.ChunkData createChunkData(@NotNull World world) {
return server.createChunkData(world);
}
@ -1195,7 +1257,8 @@ public final class Bukkit {
* @param flags an optional list of flags to set on the boss bar
* @return the created boss bar
*/
public static BossBar createBossBar(String title, BarColor color, BarStyle style, BarFlag... flags) {
@NotNull
public static BossBar createBossBar(@Nullable String title, @NotNull BarColor color, @NotNull BarStyle style, @NotNull BarFlag... flags) {
return server.createBossBar(title, color, style, flags);
}
@ -1213,7 +1276,8 @@ public final class Bukkit {
* @param flags an optional list of flags to set on the boss bar
* @return the created boss bar
*/
public static KeyedBossBar createBossBar(NamespacedKey key, String title, BarColor color, BarStyle style, BarFlag... flags) {
@NotNull
public static KeyedBossBar createBossBar(@NotNull NamespacedKey key, @Nullable String title, @NotNull BarColor color, @NotNull BarStyle style, @NotNull BarFlag... flags) {
return server.createBossBar(key, title, color, style, flags);
}
@ -1231,6 +1295,7 @@ public final class Bukkit {
*
* @return a bossbar iterator
*/
@NotNull
public static Iterator<KeyedBossBar> getBossBars() {
return server.getBossBars();
}
@ -1250,7 +1315,8 @@ public final class Bukkit {
* @param key unique bossbar key
* @return bossbar or null if not exists
*/
public static KeyedBossBar getBossBar(NamespacedKey key) {
@Nullable
public static KeyedBossBar getBossBar(@NotNull NamespacedKey key) {
return server.getBossBar(key);
}
@ -1269,7 +1335,7 @@ public final class Bukkit {
* @param key unique bossbar key
* @return true if removal succeeded or false
*/
public static boolean removeBossBar(NamespacedKey key) {
public static boolean removeBossBar(@NotNull NamespacedKey key) {
return server.removeBossBar(key);
}
@ -1279,7 +1345,8 @@ public final class Bukkit {
* @param uuid the UUID of the entity
* @return the entity with the given UUID, or null if it isn't found
*/
public static Entity getEntity(UUID uuid) {
@Nullable
public static Entity getEntity(@NotNull UUID uuid) {
return server.getEntity(uuid);
}
@ -1289,7 +1356,8 @@ public final class Bukkit {
* @param key unique advancement key
* @return advancement or null if not exists
*/
public static Advancement getAdvancement(NamespacedKey key) {
@Nullable
public static Advancement getAdvancement(@NotNull NamespacedKey key) {
return server.getAdvancement(key);
}
@ -1299,6 +1367,7 @@ public final class Bukkit {
*
* @return an advancement iterator
*/
@NotNull
public static Iterator<Advancement> advancementIterator() {
return server.advancementIterator();
}
@ -1310,7 +1379,8 @@ public final class Bukkit {
* @param material the material
* @return new data instance
*/
public static BlockData createBlockData(Material material) {
@NotNull
public static BlockData createBlockData(@NotNull Material material) {
return server.createBlockData(material);
}
@ -1322,7 +1392,8 @@ public final class Bukkit {
* @param consumer consumer to run on new instance before returning
* @return new data instance
*/
public static BlockData createBlockData(Material material, Consumer<BlockData> consumer) {
@NotNull
public static BlockData createBlockData(@NotNull Material material, @Nullable Consumer<BlockData> consumer) {
return server.createBlockData(material, consumer);
}
@ -1334,7 +1405,8 @@ public final class Bukkit {
* @return new data instance
* @throws IllegalArgumentException if the specified data is not valid
*/
public static BlockData createBlockData(String data) throws IllegalArgumentException {
@NotNull
public static BlockData createBlockData(@NotNull String data) throws IllegalArgumentException {
return server.createBlockData(data);
}
@ -1348,7 +1420,9 @@ public final class Bukkit {
* @return new data instance
* @throws IllegalArgumentException if the specified data is not valid
*/
public static BlockData createBlockData(Material material, String data) throws IllegalArgumentException {
@NotNull
@Contract("null, null -> fail")
public static BlockData createBlockData(@Nullable Material material, @Nullable String data) throws IllegalArgumentException {
return server.createBlockData(material, data);
}
@ -1370,7 +1444,8 @@ public final class Bukkit {
* @param clazz the class of the tag entries
* @return the tag or null
*/
public static <T extends Keyed> Tag<T> getTag(String registry, NamespacedKey tag, Class<T> clazz) {
@Nullable
public static <T extends Keyed> Tag<T> getTag(@NotNull String registry, @NotNull NamespacedKey tag, @NotNull Class<T> clazz) {
return server.getTag(registry, tag, clazz);
}
@ -1387,7 +1462,8 @@ public final class Bukkit {
* @param clazz the class of the tag entries
* @return all defined tags
*/
public static <T extends Keyed> Iterable<Tag<T>> getTags(String registry, Class<T> clazz) {
@NotNull
public static <T extends Keyed> Iterable<Tag<T>> getTags(@NotNull String registry, @NotNull Class<T> clazz) {
return server.getTags(registry, clazz);
}
@ -1397,7 +1473,8 @@ public final class Bukkit {
* @param key the name of the LootTable
* @return the LootTable, or null if no LootTable is found with that name
*/
public static LootTable getLootTable(NamespacedKey key) {
@Nullable
public static LootTable getLootTable(@NotNull NamespacedKey key) {
return server.getLootTable(key);
}
@ -1423,7 +1500,8 @@ public final class Bukkit {
* @deprecated draft API
*/
@Deprecated
public static List<Entity> selectEntities(CommandSender sender, String selector) throws IllegalArgumentException {
@NotNull
public static List<Entity> selectEntities(@NotNull CommandSender sender, @NotNull String selector) throws IllegalArgumentException {
return server.selectEntities(sender, selector);
}
@ -1432,6 +1510,7 @@ public final class Bukkit {
* @return the unsafe values instance
*/
@Deprecated
@NotNull
public static UnsafeValues getUnsafe() {
return server.getUnsafe();
}

18
paper-api/src/main/java/org/bukkit/ChatColor.java
View File

@ -6,6 +6,9 @@ import java.util.regex.Pattern;
import org.apache.commons.lang.Validate;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* All supported color values for chat
@ -134,6 +137,7 @@ public enum ChatColor {
return code;
}
@NotNull
@Override
public String toString() {
return toString;
@ -164,6 +168,7 @@ public enum ChatColor {
* @return Associative {@link org.bukkit.ChatColor} with the given code,
* or null if it doesn't exist
*/
@Nullable
public static ChatColor getByChar(char code) {
return BY_CHAR.get(code);
}
@ -175,7 +180,8 @@ public enum ChatColor {
* @return Associative {@link org.bukkit.ChatColor} with the given code,
* or null if it doesn't exist
*/
public static ChatColor getByChar(String code) {
@Nullable
public static ChatColor getByChar(@NotNull String code) {
Validate.notNull(code, "Code cannot be null");
Validate.isTrue(code.length() > 0, "Code must have at least one char");
@ -188,7 +194,9 @@ public enum ChatColor {
* @param input String to strip of color
* @return A copy of the input string, without any coloring
*/
public static String stripColor(final String input) {
@Contract("!null -> !null; null -> null")
@Nullable
public static String stripColor(@Nullable final String input) {
if (input == null) {
return null;
}
@ -206,7 +214,8 @@ public enum ChatColor {
* @param textToTranslate Text containing the alternate color code character.
* @return Text containing the ChatColor.COLOR_CODE color code character.
*/
public static String translateAlternateColorCodes(char altColorChar, String textToTranslate) {
@NotNull
public static String translateAlternateColorCodes(char altColorChar, @NotNull String textToTranslate) {
char[] b = textToTranslate.toCharArray();
for (int i = 0; i < b.length - 1; i++) {
if (b[i] == altColorChar && "0123456789AaBbCcDdEeFfKkLlMmNnOoRr".indexOf(b[i+1]) > -1) {
@ -223,7 +232,8 @@ public enum ChatColor {
* @param input Input string to retrieve the colors from.
* @return Any remaining ChatColors to pass onto the next line.
*/
public static String getLastColors(String input) {
@NotNull
public static String getLastColors(@NotNull String input) {
String result = "";
int length = input.length();

7
paper-api/src/main/java/org/bukkit/Chunk.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import org.bukkit.block.Block;
import org.bukkit.block.BlockState;
import org.bukkit.entity.Entity;
import org.jetbrains.annotations.NotNull;
/**
* Represents a chunk of blocks
@ -28,6 +29,7 @@ public interface Chunk {
*
* @return Parent World
*/
@NotNull
World getWorld();
/**
@ -38,6 +40,7 @@ public interface Chunk {
* @param z 0-15
* @return the Block
*/
@NotNull
Block getBlock(int x, int y, int z);
/**
@ -45,6 +48,7 @@ public interface Chunk {
*
* @return ChunkSnapshot
*/
@NotNull
ChunkSnapshot getChunkSnapshot();
/**
@ -58,6 +62,7 @@ public interface Chunk {
* raw biome temperature and rainfall
* @return ChunkSnapshot
*/
@NotNull
ChunkSnapshot getChunkSnapshot(boolean includeMaxblocky, boolean includeBiome, boolean includeBiomeTempRain);
/**
@ -65,6 +70,7 @@ public interface Chunk {
*
* @return The entities.
*/
@NotNull
Entity[] getEntities();
/**
@ -72,6 +78,7 @@ public interface Chunk {
*
* @return The tile entities.
*/
@NotNull
BlockState[] getTileEntities();
/**

5
paper-api/src/main/java/org/bukkit/ChunkSnapshot.java
View File

@ -2,6 +2,7 @@ package org.bukkit;
import org.bukkit.block.Biome;
import org.bukkit.block.data.BlockData;
import org.jetbrains.annotations.NotNull;
/**
* Represents a static, thread-safe snapshot of chunk of blocks.
@ -30,6 +31,7 @@ public interface ChunkSnapshot {
*
* @return Parent World Name
*/
@NotNull
String getWorldName();
/**
@ -40,6 +42,7 @@ public interface ChunkSnapshot {
* @param z 0-15
* @return block material type
*/
@NotNull
Material getBlockType(int x, int y, int z);
/**
@ -50,6 +53,7 @@ public interface ChunkSnapshot {
* @param z 0-15
* @return block material type
*/
@NotNull
BlockData getBlockData(int x, int y, int z);
/**
@ -101,6 +105,7 @@ public interface ChunkSnapshot {
* @param z Z-coordinate (0-15)
* @return Biome at given coordinate
*/
@NotNull
Biome getBiome(int x, int z);
/**

2
paper-api/src/main/java/org/bukkit/CoalType.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
/**
* Represents the two types of coal
@ -38,6 +39,7 @@ public enum CoalType {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static CoalType getByData(final byte data) {
return BY_DATA.get(data);
}

20
paper-api/src/main/java/org/bukkit/Color.java
View File

@ -7,6 +7,7 @@ import org.bukkit.configuration.serialization.ConfigurationSerializable;
import org.bukkit.configuration.serialization.SerializableAs;
import com.google.common.collect.ImmutableMap;
import org.jetbrains.annotations.NotNull;
/**
* A container for a color palette. This class is immutable; the set methods
@ -115,6 +116,7 @@ public final class Color implements ConfigurationSerializable {
* @return a new Color object for the red, green, blue
* @throws IllegalArgumentException if any value is strictly {@literal >255 or <0}
*/
@NotNull
public static Color fromRGB(int red, int green, int blue) throws IllegalArgumentException {
return new Color(red, green, blue);
}
@ -128,6 +130,7 @@ public final class Color implements ConfigurationSerializable {
* @return a new Color object for the red, green, blue
* @throws IllegalArgumentException if any value is strictly {@literal >255 or <0}
*/
@NotNull
public static Color fromBGR(int blue, int green, int red) throws IllegalArgumentException {
return new Color(red, green, blue);
}
@ -141,6 +144,7 @@ public final class Color implements ConfigurationSerializable {
* @throws IllegalArgumentException if any data is in the highest order 8
* bits
*/
@NotNull
public static Color fromRGB(int rgb) throws IllegalArgumentException {
Validate.isTrue((rgb >> 24) == 0, "Extrenuous data in: ", rgb);
return fromRGB(rgb >> 16 & BIT_MASK, rgb >> 8 & BIT_MASK, rgb >> 0 & BIT_MASK);
@ -155,6 +159,7 @@ public final class Color implements ConfigurationSerializable {
* @throws IllegalArgumentException if any data is in the highest order 8
* bits
*/
@NotNull
public static Color fromBGR(int bgr) throws IllegalArgumentException {
Validate.isTrue((bgr >> 24) == 0, "Extrenuous data in: ", bgr);
return fromBGR(bgr >> 16 & BIT_MASK, bgr >> 8 & BIT_MASK, bgr >> 0 & BIT_MASK);
@ -185,6 +190,7 @@ public final class Color implements ConfigurationSerializable {
* @param red the red component, from 0 to 255
* @return a new color object with the red component
*/
@NotNull
public Color setRed(int red) {
return fromRGB(red, getGreen(), getBlue());
}
@ -204,6 +210,7 @@ public final class Color implements ConfigurationSerializable {
* @param green the red component, from 0 to 255
* @return a new color object with the red component
*/
@NotNull
public Color setGreen(int green) {
return fromRGB(getRed(), green, getBlue());
}
@ -223,6 +230,7 @@ public final class Color implements ConfigurationSerializable {
* @param blue the red component, from 0 to 255
* @return a new color object with the red component
*/
@NotNull
public Color setBlue(int blue) {
return fromRGB(getRed(), getGreen(), blue);
}
@ -251,7 +259,8 @@ public final class Color implements ConfigurationSerializable {
* @return A new color with the changed rgb components
*/
// TODO: Javadoc what this method does, not what it mimics. API != Implementation
public Color mixDyes(DyeColor... colors) {
@NotNull
public Color mixDyes(@NotNull DyeColor... colors) {
Validate.noNullElements(colors, "Colors cannot be null");
Color[] toPass = new Color[colors.length];
@ -270,7 +279,8 @@ public final class Color implements ConfigurationSerializable {
* @return A new color with the changed rgb components
*/
// TODO: Javadoc what this method does, not what it mimics. API != Implementation
public Color mixColors(Color... colors) {
@NotNull
public Color mixColors(@NotNull Color... colors) {
Validate.noNullElements(colors, "Colors cannot be null");
int totalRed = this.getRed();
@ -309,6 +319,7 @@ public final class Color implements ConfigurationSerializable {
return asRGB() ^ Color.class.hashCode();
}
@NotNull
public Map<String, Object> serialize() {
return ImmutableMap.<String, Object>of(
"RED", getRed(),
@ -318,7 +329,8 @@ public final class Color implements ConfigurationSerializable {
}
@SuppressWarnings("javadoc")
public static Color deserialize(Map<String, Object> map) {
@NotNull
public static Color deserialize(@NotNull Map<String, Object> map) {
return fromRGB(
asInt("RED", map),
asInt("GREEN", map),
@ -326,7 +338,7 @@ public final class Color implements ConfigurationSerializable {
);
}
private static int asInt(String string, Map<String, Object> map) {
private static int asInt(@NotNull String string, @NotNull Map<String, Object> map) {
Object value = map.get(string);
if (value == null) {
throw new IllegalArgumentException(string + " not in map " + map);

2
paper-api/src/main/java/org/bukkit/CropState.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
/**
* Represents the different growth states of crops
@ -69,6 +70,7 @@ public enum CropState {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static CropState getByData(final byte data) {
return BY_DATA.get(data);
}

2
paper-api/src/main/java/org/bukkit/Difficulty.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
/**
* Represents the various difficulty levels that are available.
@ -60,6 +61,7 @@ public enum Difficulty {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static Difficulty getByValue(final int value) {
return BY_ID.get(value);
}

17
paper-api/src/main/java/org/bukkit/DyeColor.java
View File

@ -3,6 +3,8 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.ImmutableMap;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* All supported color values for dyes and cloth
@ -83,7 +85,7 @@ public enum DyeColor {
private final static Map<Color, DyeColor> BY_COLOR;
private final static Map<Color, DyeColor> BY_FIREWORK;
private DyeColor(final int woolData, final int dyeData, Color color, Color firework) {
private DyeColor(final int woolData, final int dyeData, @NotNull Color color, @NotNull Color firework) {
this.woolData = (byte) woolData;
this.dyeData = (byte) dyeData;
this.color = color;
@ -119,6 +121,7 @@ public enum DyeColor {
*
* @return The {@link Color} that this dye represents
*/
@NotNull
public Color getColor() {
return color;
}
@ -128,6 +131,7 @@ public enum DyeColor {
*
* @return The {@link Color} that this dye represents
*/
@NotNull
public Color getFireworkColor() {
return firework;
}
@ -142,6 +146,7 @@ public enum DyeColor {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static DyeColor getByWoolData(final byte data) {
int i = 0xff & data;
if (i >= BY_WOOL_DATA.length) {
@ -160,6 +165,7 @@ public enum DyeColor {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static DyeColor getByDyeData(final byte data) {
int i = 0xff & data;
if (i >= BY_DYE_DATA.length) {
@ -175,7 +181,8 @@ public enum DyeColor {
* @return The {@link DyeColor} representing the given value, or null if
* it doesn't exist
*/
public static DyeColor getByColor(final Color color) {
@Nullable
public static DyeColor getByColor(@NotNull final Color color) {
return BY_COLOR.get(color);
}
@ -186,7 +193,8 @@ public enum DyeColor {
* @return The {@link DyeColor} representing the given value, or null if
* it doesn't exist
*/
public static DyeColor getByFireworkColor(final Color color) {
@Nullable
public static DyeColor getByFireworkColor(@NotNull final Color color) {
return BY_FIREWORK.get(color);
}
@ -198,7 +206,8 @@ public enum DyeColor {
* @deprecated legacy use only
*/
@Deprecated
public static DyeColor legacyValueOf(String name) {
@NotNull
public static DyeColor legacyValueOf(@Nullable String name) {
return "SILVER".equals(name) ? DyeColor.LIGHT_GRAY : DyeColor.valueOf(name);
}

9
paper-api/src/main/java/org/bukkit/Effect.java
View File

@ -6,6 +6,8 @@ import com.google.common.collect.Maps;
import org.bukkit.block.BlockFace;
import org.bukkit.potion.Potion;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* A list of effects that the server is able to send to players.
@ -203,11 +205,11 @@ public enum Effect {
private final Class<?> data;
private static final Map<Integer, Effect> BY_ID = Maps.newHashMap();
Effect(int id, Type type) {
Effect(int id, @NotNull Type type) {
this(id, type, null);
}
Effect(int id, Type type, Class<?> data) {
Effect(int id, @NotNull Type type, @Nullable Class<?> data) {
this.id = id;
this.type = type;
this.data = data;
@ -227,6 +229,7 @@ public enum Effect {
/**
* @return The type of the effect.
*/
@NotNull
public Type getType() {
return this.type;
}
@ -235,6 +238,7 @@ public enum Effect {
* @return The class which represents data for this effect, or null if
* none
*/
@Nullable
public Class<?> getData() {
return this.data;
}
@ -247,6 +251,7 @@ public enum Effect {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static Effect getById(int id) {
return BY_ID.get(id);
}

6
paper-api/src/main/java/org/bukkit/EntityEffect.java
View File

@ -18,6 +18,8 @@ import org.bukkit.entity.Villager;
import org.bukkit.entity.Witch;
import org.bukkit.entity.Wolf;
import org.bukkit.entity.ZombieVillager;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* A list of all Effects that can happen to entities.
@ -153,7 +155,7 @@ public enum EntityEffect {
private final Class<? extends Entity> applicable;
private final static Map<Byte, EntityEffect> BY_DATA = Maps.newHashMap();
EntityEffect(final int data, Class<? extends Entity> clazz) {
EntityEffect(final int data, @NotNull Class<? extends Entity> clazz) {
this.data = (byte) data;
this.applicable = clazz;
}
@ -174,6 +176,7 @@ public enum EntityEffect {
*
* @return applicable class
*/
@NotNull
public Class<? extends Entity> getApplicable() {
return applicable;
}
@ -187,6 +190,7 @@ public enum EntityEffect {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static EntityEffect getByData(final byte data) {
return BY_DATA.get(data);
}

37
paper-api/src/main/java/org/bukkit/FireworkEffect.java
View File

@ -9,6 +9,7 @@ import org.bukkit.configuration.serialization.SerializableAs;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import org.jetbrains.annotations.NotNull;
/**
* Represents a single firework effect.
@ -48,6 +49,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
*
* @return A utility object for building a firework effect
*/
@NotNull
public static Builder builder() {
return new Builder();
}
@ -73,7 +75,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @return This object, for chaining
* @throws IllegalArgumentException If type is null
*/
public Builder with(Type type) throws IllegalArgumentException {
@NotNull
public Builder with(@NotNull Type type) throws IllegalArgumentException {
Validate.notNull(type, "Cannot have null type");
this.type = type;
return this;
@ -84,6 +87,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
*
* @return This object, for chaining
*/
@NotNull
public Builder withFlicker() {
flicker = true;
return this;
@ -95,6 +99,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @param flicker true if it should flicker, false if not
* @return This object, for chaining
*/
@NotNull
public Builder flicker(boolean flicker) {
this.flicker = flicker;
return this;
@ -105,6 +110,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
*
* @return This object, for chaining
*/
@NotNull
public Builder withTrail() {
trail = true;
return this;
@ -116,6 +122,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @param trail true if it should have a trail, false for no trail
* @return This object, for chaining
*/
@NotNull
public Builder trail(boolean trail) {
this.trail = trail;
return this;
@ -128,7 +135,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @return This object, for chaining
* @throws IllegalArgumentException If color is null
*/
public Builder withColor(Color color) throws IllegalArgumentException {
@NotNull
public Builder withColor(@NotNull Color color) throws IllegalArgumentException {
Validate.notNull(color, "Cannot have null color");
colors.add(color);
@ -145,7 +153,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/
public Builder withColor(Color... colors) throws IllegalArgumentException {
@NotNull
public Builder withColor(@NotNull Color... colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors");
if (colors.length == 0) {
return this;
@ -170,7 +179,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/
public Builder withColor(Iterable<?> colors) throws IllegalArgumentException {
@NotNull
public Builder withColor(@NotNull Iterable<?> colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors");
ImmutableList.Builder<Color> list = this.colors;
@ -193,7 +203,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/
public Builder withFade(Color color) throws IllegalArgumentException {
@NotNull
public Builder withFade(@NotNull Color color) throws IllegalArgumentException {
Validate.notNull(color, "Cannot have null color");
if (fadeColors == null) {
@ -214,7 +225,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/
public Builder withFade(Color... colors) throws IllegalArgumentException {
@NotNull
public Builder withFade(@NotNull Color... colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors");
if (colors.length == 0) {
return this;
@ -243,7 +255,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/
public Builder withFade(Iterable<?> colors) throws IllegalArgumentException {
@NotNull
public Builder withFade(@NotNull Iterable<?> colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors");
ImmutableList.Builder<Color> list = this.fadeColors;
@ -269,6 +282,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
*
* @return The representative firework effect
*/
@NotNull
public FireworkEffect build() {
return new FireworkEffect(
flicker,
@ -293,7 +307,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
private final Type type;
private String string = null;
FireworkEffect(boolean flicker, boolean trail, ImmutableList<Color> colors, ImmutableList<Color> fadeColors, Type type) {
FireworkEffect(boolean flicker, boolean trail, @NotNull ImmutableList<Color> colors, @NotNull ImmutableList<Color> fadeColors, @NotNull Type type) {
if (colors.isEmpty()) {
throw new IllegalStateException("Cannot make FireworkEffect without any color");
}
@ -327,6 +341,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
*
* @return An immutable list of the primary colors
*/
@NotNull
public List<Color> getColors() {
return colors;
}
@ -336,6 +351,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
*
* @return An immutable list of the fade colors
*/
@NotNull
public List<Color> getFadeColors() {
return fadeColors;
}
@ -345,6 +361,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
*
* @return The effect type
*/
@NotNull
public Type getType() {
return type;
}
@ -354,7 +371,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @param map the map to deserialize
* @return the resulting serializable
*/
public static ConfigurationSerializable deserialize(Map<String, Object> map) {
@NotNull
public static ConfigurationSerializable deserialize(@NotNull Map<String, Object> map) {
Type type = Type.valueOf((String) map.get(TYPE));
return builder()
@ -366,6 +384,7 @@ public final class FireworkEffect implements ConfigurationSerializable {
.build();
}
@NotNull
@Override
public Map<String, Object> serialize() {
return ImmutableMap.<String, Object>of(

2
paper-api/src/main/java/org/bukkit/GameMode.java
View File

@ -5,6 +5,7 @@ import java.util.Map;
import org.bukkit.entity.HumanEntity;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
/**
* Represents the various type of game modes that {@link HumanEntity}s may
@ -61,6 +62,7 @@ public enum GameMode {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static GameMode getByValue(final int value) {
return BY_ID.get(value);
}

11
paper-api/src/main/java/org/bukkit/GameRule.java
View File

@ -1,6 +1,9 @@
package org.bukkit;
import com.google.common.base.Preconditions;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.HashMap;
import java.util.Map;
@ -150,7 +153,7 @@ public final class GameRule<T> {
private final String name;
private final Class<T> type;
private GameRule(String name, Class<T> clazz) {
private GameRule(@NotNull String name, @NotNull Class<T> clazz) {
Preconditions.checkNotNull(name, "GameRule name cannot be null");
Preconditions.checkNotNull(clazz, "GameRule type cannot be null");
Preconditions.checkArgument(clazz == Boolean.class || clazz == Integer.class, "Must be of type Boolean or Integer. Found %s ", clazz.getName());
@ -164,6 +167,7 @@ public final class GameRule<T> {
*
* @return the name of this GameRule
*/
@NotNull
public String getName() {
return name;
}
@ -173,6 +177,7 @@ public final class GameRule<T> {
*
* @return the rule type; Integer or Boolean
*/
@NotNull
public Class<T> getType() {
return type;
}
@ -201,7 +206,8 @@ public final class GameRule<T> {
* @return the {@link GameRule} or null if no GameRule matches the given
* name
*/
public static GameRule<?> getByName(String rule) {
@Nullable
public static GameRule<?> getByName(@NotNull String rule) {
Preconditions.checkNotNull(rule, "Rule cannot be null");
return gameRules.get(rule);
}
@ -211,6 +217,7 @@ public final class GameRule<T> {
*
* @return an immutable collection containing all registered GameRules.
*/
@NotNull
public static GameRule<?>[] values() {
return gameRules.values().toArray(new GameRule<?>[gameRules.size()]);
}

2
paper-api/src/main/java/org/bukkit/GrassSpecies.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
/**
* Represents the different types of grass.
@ -49,6 +50,7 @@ public enum GrassSpecies {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static GrassSpecies getByData(final byte data) {
return BY_DATA.get(data);
}

2
paper-api/src/main/java/org/bukkit/Instrument.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
public enum Instrument {
@ -76,6 +77,7 @@ public enum Instrument {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static Instrument getByType(final byte type) {
return BY_DATA.get(type);
}

3
paper-api/src/main/java/org/bukkit/Keyed.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
/**
* Represents an object which has a {@link NamespacedKey} attached to it.
*/
@ -10,5 +12,6 @@ public interface Keyed {
*
* @return this object's key
*/
@NotNull
NamespacedKey getKey();
}

41
paper-api/src/main/java/org/bukkit/Location.java
View File

@ -7,6 +7,8 @@ import org.bukkit.block.Block;
import org.bukkit.configuration.serialization.ConfigurationSerializable;
import org.bukkit.util.NumberConversions;
import org.bukkit.util.Vector;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a 3-dimensional position in a world.
@ -32,7 +34,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @param y The y-coordinate of this new location
* @param z The z-coordinate of this new location
*/
public Location(final World world, final double x, final double y, final double z) {
public Location(@Nullable final World world, final double x, final double y, final double z) {
this(world, x, y, z, 0, 0);
}
@ -46,7 +48,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @param yaw The absolute rotation on the x-plane, in degrees
* @param pitch The absolute rotation on the y-plane, in degrees
*/
public Location(final World world, final double x, final double y, final double z, final float yaw, final float pitch) {
public Location(@Nullable final World world, final double x, final double y, final double z, final float yaw, final float pitch) {
this.world = world;
this.x = x;
this.y = y;
@ -60,7 +62,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
*
* @param world New world that this location resides in
*/
public void setWorld(World world) {
public void setWorld(@Nullable World world) {
this.world = world;
}
@ -69,6 +71,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
*
* @return World that contains this location
*/
@Nullable
public World getWorld() {
return world;
}
@ -78,6 +81,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
*
* @return Chunk at the represented location
*/
@NotNull
public Chunk getChunk() {
return world.getChunkAt(this);
}
@ -87,6 +91,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
*
* @return Block at the represented location
*/
@NotNull
public Block getBlock() {
return world.getBlockAt(this);
}
@ -250,6 +255,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @return a vector pointing the direction of this location's {@link
* #getPitch() pitch} and {@link #getYaw() yaw}
*/
@NotNull
public Vector getDirection() {
Vector vector = new Vector();
@ -273,7 +279,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @param vector the direction vector
* @return the same location
*/
public Location setDirection(Vector vector) {
@NotNull
public Location setDirection(@NotNull Vector vector) {
/*
* Sin = Opp / Hyp
* Cos = Adj / Hyp
@ -310,7 +317,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @return the same location
* @throws IllegalArgumentException for differing worlds
*/
public Location add(Location vec) {
@NotNull
public Location add(@NotNull Location vec) {
if (vec == null || vec.getWorld() != getWorld()) {
throw new IllegalArgumentException("Cannot add Locations of differing worlds");
}
@ -328,7 +336,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @param vec Vector to use
* @return the same location
*/
public Location add(Vector vec) {
@NotNull
public Location add(@NotNull Vector vec) {
this.x += vec.getX();
this.y += vec.getY();
this.z += vec.getZ();
@ -344,6 +353,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @param z Z coordinate
* @return the same location
*/
@NotNull
public Location add(double x, double y, double z) {
this.x += x;
this.y += y;
@ -359,7 +369,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @return the same location
* @throws IllegalArgumentException for differing worlds
*/
public Location subtract(Location vec) {
@NotNull
public Location subtract(@NotNull Location vec) {
if (vec == null || vec.getWorld() != getWorld()) {
throw new IllegalArgumentException("Cannot add Locations of differing worlds");
}
@ -377,7 +388,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @param vec The vector to use
* @return the same location
*/
public Location subtract(Vector vec) {
@NotNull
public Location subtract(@NotNull Vector vec) {
this.x -= vec.getX();
this.y -= vec.getY();
this.z -= vec.getZ();
@ -394,6 +406,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @param z Z coordinate
* @return the same location
*/
@NotNull
public Location subtract(double x, double y, double z) {
this.x -= x;
this.y -= y;
@ -439,7 +452,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @return the distance
* @throws IllegalArgumentException for differing worlds
*/
public double distance(Location o) {
public double distance(@NotNull Location o) {
return Math.sqrt(distanceSquared(o));
}
@ -451,7 +464,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @return the distance
* @throws IllegalArgumentException for differing worlds
*/
public double distanceSquared(Location o) {
public double distanceSquared(@NotNull Location o) {
if (o == null) {
throw new IllegalArgumentException("Cannot measure distance to a null location");
} else if (o.getWorld() == null || getWorld() == null) {
@ -471,6 +484,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @see Vector
* @return the same location
*/
@NotNull
public Location multiply(double m) {
x *= m;
y *= m;
@ -484,6 +498,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @see Vector
* @return the same location
*/
@NotNull
public Location zero() {
x = 0;
y = 0;
@ -546,11 +561,13 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @return New Vector containing the coordinates represented by this
* Location
*/
@NotNull
public Vector toVector() {
return new Vector(x, y, z);
}
@Override
@NotNull
public Location clone() {
try {
return (Location) super.clone();
@ -584,6 +601,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
}
@Utility
@NotNull
public Map<String, Object> serialize() {
Map<String, Object> data = new HashMap<String, Object>();
data.put("world", this.world.getName());
@ -606,7 +624,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
* @throws IllegalArgumentException if the world don't exists
* @see ConfigurationSerializable
*/
public static Location deserialize(Map<String, Object> args) {
@NotNull
public static Location deserialize(@NotNull Map<String, Object> args) {
World world = Bukkit.getWorld((String) args.get("world"));
if (world == null) {
throw new IllegalArgumentException("unknown world");

30
paper-api/src/main/java/org/bukkit/Material.java
View File

@ -68,6 +68,8 @@ import org.bukkit.block.data.type.TripwireHook;
import org.bukkit.block.data.type.TurtleEgg;
import org.bukkit.block.data.type.WallSign;
import org.bukkit.material.MaterialData;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* An enum of all material IDs accepted by the official server and client
@ -2955,15 +2957,15 @@ public enum Material implements Keyed {
this(id, stack, durability, MaterialData.class);
}
private Material(final int id, final Class<?> data) {
private Material(final int id, @NotNull final Class<?> data) {
this(id, 64, data);
}
private Material(final int id, final int stack, final Class<?> data) {
private Material(final int id, final int stack, @NotNull final Class<?> data) {
this(id, stack, 0, data);
}
private Material(final int id, final int stack, final int durability, final Class<?> data) {
private Material(final int id, final int stack, final int durability, @NotNull final Class<?> data) {
this.id = id;
this.durability = (short) durability;
this.maxStack = stack;
@ -3005,6 +3007,7 @@ public enum Material implements Keyed {
return legacy;
}
@NotNull
@Override
public NamespacedKey getKey() {
Validate.isTrue(!legacy, "Cannot get key of Legacy Material");
@ -3035,6 +3038,7 @@ public enum Material implements Keyed {
*
* @return new data instance
*/
@NotNull
public BlockData createBlockData() {
return Bukkit.createBlockData(this);
}
@ -3046,7 +3050,8 @@ public enum Material implements Keyed {
* @param consumer consumer to run on new instance before returning
* @return new data instance
*/
public BlockData createBlockData(Consumer<BlockData> consumer) {
@NotNull
public BlockData createBlockData(@Nullable Consumer<BlockData> consumer) {
return Bukkit.createBlockData(this, consumer);
}
@ -3059,7 +3064,8 @@ public enum Material implements Keyed {
* @return new data instance
* @throws IllegalArgumentException if the specified data is not valid
*/
public BlockData createBlockData(String data) throws IllegalArgumentException {
@NotNull
public BlockData createBlockData(@Nullable String data) throws IllegalArgumentException {
return Bukkit.createBlockData(this, data);
}
@ -3068,6 +3074,7 @@ public enum Material implements Keyed {
*
* @return MaterialData associated with this Material
*/
@NotNull
public Class<? extends MaterialData> getData() {
Validate.isTrue(legacy, "Cannot get data class of Modern Material");
return ctor.getDeclaringClass();
@ -3082,6 +3089,7 @@ public enum Material implements Keyed {
* @deprecated Magic value
*/
@Deprecated
@NotNull
public MaterialData getNewData(final byte raw) {
Validate.isTrue(legacy, "Cannot get new data of Modern Material");
try {
@ -3804,7 +3812,8 @@ public enum Material implements Keyed {
* @param name Name of the material to get
* @return Material if found, or null
*/
public static Material getMaterial(final String name) {
@Nullable
public static Material getMaterial(@NotNull final String name) {
return getMaterial(name, false);
}
@ -3818,7 +3827,8 @@ public enum Material implements Keyed {
* @param legacyName whether this is a legacy name
* @return Material if found, or null
*/
public static Material getMaterial(String name, boolean legacyName) {
@Nullable
public static Material getMaterial(@NotNull String name, boolean legacyName) {
if (legacyName) {
if (!name.startsWith(LEGACY_PREFIX)) {
name = LEGACY_PREFIX + name;
@ -3841,7 +3851,8 @@ public enum Material implements Keyed {
* @param name Name of the material to get
* @return Material if found, or null
*/
public static Material matchMaterial(final String name) {
@Nullable
public static Material matchMaterial(@NotNull final String name) {
return matchMaterial(name, false);
}
@ -3856,7 +3867,8 @@ public enum Material implements Keyed {
* @param legacyName whether this is a legacy name
* @return Material if found, or null
*/
public static Material matchMaterial(final String name, boolean legacyName) {
@Nullable
public static Material matchMaterial(@NotNull final String name, boolean legacyName) {
Validate.notNull(name, "Name cannot be null");
String filtered = name;

5
paper-api/src/main/java/org/bukkit/Nameable.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.Nullable;
public interface Nameable {
/**
@ -11,6 +13,7 @@ public interface Nameable {
*
* @return name of the mob/block or null
*/
@Nullable
public String getCustomName();
/**
@ -24,5 +27,5 @@ public interface Nameable {
*
* @param name the name to set
*/
public void setCustomName(String name);
public void setCustomName(@Nullable String name);
}

11
paper-api/src/main/java/org/bukkit/NamespacedKey.java
View File

@ -5,6 +5,7 @@ import java.util.Locale;
import java.util.UUID;
import java.util.regex.Pattern;
import org.bukkit.plugin.Plugin;
import org.jetbrains.annotations.NotNull;
/**
* Represents a String based key which consists of two components - a namespace
@ -43,7 +44,7 @@ public final class NamespacedKey {
* @deprecated should never be used by plugins, for internal use only!!
*/
@Deprecated
public NamespacedKey(String namespace, String key) {
public NamespacedKey(@NotNull String namespace, @NotNull String key) {
Preconditions.checkArgument(namespace != null && VALID_NAMESPACE.matcher(namespace).matches(), "Invalid namespace. Must be [a-z0-9._-]: %s", namespace);
Preconditions.checkArgument(key != null && VALID_KEY.matcher(key).matches(), "Invalid key. Must be [a-z0-9/._-]: %s", key);
@ -66,7 +67,7 @@ public final class NamespacedKey {
* @param plugin the plugin to use for the namespace
* @param key the key to create
*/
public NamespacedKey(Plugin plugin, String key) {
public NamespacedKey(@NotNull Plugin plugin, @NotNull String key) {
Preconditions.checkArgument(plugin != null, "Plugin cannot be null");
Preconditions.checkArgument(key != null, "Key cannot be null");
@ -81,10 +82,12 @@ public final class NamespacedKey {
Preconditions.checkArgument(string.length() < 256, "NamespacedKey must be less than 256 characters (%s)", string);
}
@NotNull
public String getNamespace() {
return namespace;
}
@NotNull
public String getKey() {
return key;
}
@ -121,6 +124,7 @@ public final class NamespacedKey {
* @deprecated should never be used by plugins, for internal use only!!
*/
@Deprecated
@NotNull
public static NamespacedKey randomKey() {
return new NamespacedKey(BUKKIT, UUID.randomUUID().toString());
}
@ -131,7 +135,8 @@ public final class NamespacedKey {
* @param key the key to use
* @return new key in the Minecraft namespace
*/
public static NamespacedKey minecraft(String key) {
@NotNull
public static NamespacedKey minecraft(@NotNull String key) {
return new NamespacedKey(MINECRAFT, key);
}
}

17
paper-api/src/main/java/org/bukkit/Note.java
View File

@ -5,6 +5,8 @@ import java.util.Map;
import org.apache.commons.lang.Validate;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* A note class to store a specific note.
@ -100,6 +102,7 @@ public class Note {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static Tone getById(byte id) {
return BY_DATA.get(id);
}
@ -139,7 +142,7 @@ public class Note {
* to be F#.
* @param sharped Set if the tone is sharped (e.g. for F#).
*/
public Note(int octave, Tone tone, boolean sharped) {
public Note(int octave, @NotNull Tone tone, boolean sharped) {
if (sharped && !tone.isSharpable()) {
tone = Tone.values()[tone.ordinal() + 1];
sharped = false;
@ -158,7 +161,8 @@ public class Note {
* @param tone The tone within the octave.
* @return The new note.
*/
public static Note flat(int octave, Tone tone) {
@NotNull
public static Note flat(int octave, @NotNull Tone tone) {
Validate.isTrue(octave != 2, "Octave cannot be 2 for flats");
tone = tone == Tone.G ? Tone.F : Tone.values()[tone.ordinal() - 1];
return new Note(octave, tone, tone.isSharpable());
@ -172,7 +176,8 @@ public class Note {
* to be F#.
* @return The new note.
*/
public static Note sharp(int octave, Tone tone) {
@NotNull
public static Note sharp(int octave, @NotNull Tone tone) {
return new Note(octave, tone, true);
}
@ -183,7 +188,8 @@ public class Note {
* @param tone The tone within the octave.
* @return The new note.
*/
public static Note natural(int octave, Tone tone) {
@NotNull
public static Note natural(int octave, @NotNull Tone tone) {
Validate.isTrue(octave != 2, "Octave cannot be 2 for naturals");
return new Note(octave, tone, false);
}
@ -191,6 +197,7 @@ public class Note {
/**
* @return The note a semitone above this one.
*/
@NotNull
public Note sharped() {
Validate.isTrue(note < 24, "This note cannot be sharped because it is the highest known note!");
return new Note(note + 1);
@ -199,6 +206,7 @@ public class Note {
/**
* @return The note a semitone below this one.
*/
@NotNull
public Note flattened() {
Validate.isTrue(note > 0, "This note cannot be flattened because it is the lowest known note!");
return new Note(note - 1);
@ -233,6 +241,7 @@ public class Note {
*
* @return the tone of this note.
*/
@NotNull
public Tone getTone() {
return Tone.getById(getToneByte());
}

6
paper-api/src/main/java/org/bukkit/OfflinePlayer.java
View File

@ -6,6 +6,8 @@ import org.bukkit.configuration.serialization.ConfigurationSerializable;
import org.bukkit.entity.AnimalTamer;
import org.bukkit.entity.Player;
import org.bukkit.permissions.ServerOperator;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
public interface OfflinePlayer extends ServerOperator, AnimalTamer, ConfigurationSerializable {
@ -24,6 +26,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
*
* @return Player name or null if we have not seen a name for this player yet
*/
@Nullable
public String getName();
/**
@ -31,6 +34,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
*
* @return Player UUID
*/
@NotNull
public UUID getUniqueId();
/**
@ -62,6 +66,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
*
* @return Online player
*/
@Nullable
public Player getPlayer();
/**
@ -101,6 +106,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
*
* @return Bed Spawn Location if bed exists, otherwise null.
*/
@Nullable
public Location getBedSpawnLocation();
}

7
paper-api/src/main/java/org/bukkit/Particle.java
View File

@ -4,6 +4,7 @@ import com.google.common.base.Preconditions;
import org.bukkit.block.data.BlockData;
import org.bukkit.inventory.ItemStack;
import org.bukkit.material.MaterialData;
import org.jetbrains.annotations.NotNull;
public enum Particle {
EXPLOSION_NORMAL,
@ -70,7 +71,7 @@ public enum Particle {
dataType = Void.class;
}
Particle(Class<?> data) {
Particle(@NotNull Class<?> data) {
dataType = data;
}
@ -78,6 +79,7 @@ public enum Particle {
* Returns the required data type for the particle
* @return the required data type
*/
@NotNull
public Class<?> getDataType() {
return dataType;
}
@ -91,7 +93,7 @@ public enum Particle {
private final Color color;
private final float size;
public DustOptions(Color color, float size) {
public DustOptions(@NotNull Color color, float size) {
Preconditions.checkArgument(color != null, "color");
this.color = color;
this.size = size;
@ -102,6 +104,7 @@ public enum Particle {
*
* @return particle color
*/
@NotNull
public Color getColor() {
return color;
}

4
paper-api/src/main/java/org/bukkit/Rotation.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
/**
* An enum to specify a rotation based orientation, like that on a clock.
* <p>
@ -48,6 +50,7 @@ public enum Rotation {
*
* @return the relative rotation
*/
@NotNull
public Rotation rotateClockwise() {
return rotations[(this.ordinal() + 1) & 0x7];
}
@ -57,6 +60,7 @@ public enum Rotation {
*
* @return the relative rotation
*/
@NotNull
public Rotation rotateCounterClockwise() {
return rotations[(this.ordinal() - 1) & 0x7];
}

2
paper-api/src/main/java/org/bukkit/SandstoneType.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
/**
* Represents the three different types of Sandstone
@ -39,6 +40,7 @@ public enum SandstoneType {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static SandstoneType getByData(final byte data) {
return BY_DATA.get(data);
}

170
paper-api/src/main/java/org/bukkit/Server.java
View File

@ -51,6 +51,9 @@ import org.bukkit.generator.ChunkGenerator;
import org.bukkit.inventory.ItemFactory;
import org.bukkit.inventory.meta.ItemMeta;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a server implementation.
@ -78,6 +81,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return name of this server implementation
*/
@NotNull
public String getName();
/**
@ -85,6 +89,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return version of this server implementation
*/
@NotNull
public String getVersion();
/**
@ -92,6 +97,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return version of Bukkit
*/
@NotNull
public String getBukkitVersion();
/**
@ -121,6 +127,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a view of currently online players.
*/
@NotNull
public Collection<? extends Player> getOnlinePlayers();
/**
@ -151,6 +158,7 @@ public interface Server extends PluginMessageRecipient {
* @return the IP string that this server is bound to, otherwise empty
* string
*/
@NotNull
public String getIp();
/**
@ -160,6 +168,7 @@ public interface Server extends PluginMessageRecipient {
* @deprecated not a standard server property
*/
@Deprecated
@NotNull
public String getServerName();
/**
@ -170,6 +179,7 @@ public interface Server extends PluginMessageRecipient {
* @deprecated not a standard server property
*/
@Deprecated
@NotNull
public String getServerId();
/**
@ -177,6 +187,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1)
*/
@NotNull
public String getWorldType();
/**
@ -219,6 +230,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a set containing all whitelisted players
*/
@NotNull
public Set<OfflinePlayer> getWhitelistedPlayers();
/**
@ -235,7 +247,7 @@ public interface Server extends PluginMessageRecipient {
* @param message the message
* @return the number of players
*/
public int broadcastMessage(String message);
public int broadcastMessage(@NotNull String message);
/**
* Gets the name of the update folder. The update folder is used to safely
@ -245,6 +257,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the name of the update folder
*/
@NotNull
public String getUpdateFolder();
/**
@ -253,6 +266,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the update folder
*/
@NotNull
public File getUpdateFolderFile();
/**
@ -315,7 +329,8 @@ public interface Server extends PluginMessageRecipient {
* @return a player if one was found, null otherwise
*/
@Deprecated
public Player getPlayer(String name);
@Nullable
public Player getPlayer(@NotNull String name);
/**
* Gets the player with the exact given name, case insensitive.
@ -326,7 +341,8 @@ public interface Server extends PluginMessageRecipient {
* @return a player object if one was found, null otherwise
*/
@Deprecated
public Player getPlayerExact(String name);
@Nullable
public Player getPlayerExact(@NotNull String name);
/**
* Attempts to match any players with the given name, and returns a list
@ -341,7 +357,8 @@ public interface Server extends PluginMessageRecipient {
* @return list of all possible players
*/
@Deprecated
public List<Player> matchPlayer(String name);
@NotNull
public List<Player> matchPlayer(@NotNull String name);
/**
* Gets the player with the given UUID.
@ -349,13 +366,15 @@ public interface Server extends PluginMessageRecipient {
* @param id UUID of the player to retrieve
* @return a player object if one was found, null otherwise
*/
public Player getPlayer(UUID id);
@Nullable
public Player getPlayer(@NotNull UUID id);
/**
* Gets the plugin manager for interfacing with plugins.
*
* @return a plugin manager for this Server instance
*/
@NotNull
public PluginManager getPluginManager();
/**
@ -363,6 +382,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a scheduling service for this server
*/
@NotNull
public BukkitScheduler getScheduler();
/**
@ -370,6 +390,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return s services manager
*/
@NotNull
public ServicesManager getServicesManager();
/**
@ -377,6 +398,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a list of worlds
*/
@NotNull
public List<World> getWorlds();
/**
@ -389,7 +411,8 @@ public interface Server extends PluginMessageRecipient {
* @param creator the options to use when creating the world
* @return newly created or loaded world
*/
public World createWorld(WorldCreator creator);
@Nullable
public World createWorld(@NotNull WorldCreator creator);
/**
* Unloads a world with the given name.
@ -398,7 +421,7 @@ public interface Server extends PluginMessageRecipient {
* @param save whether to save the chunks before unloading
* @return true if successful, false otherwise
*/
public boolean unloadWorld(String name, boolean save);
public boolean unloadWorld(@NotNull String name, boolean save);
/**
* Unloads the given world.
@ -407,7 +430,7 @@ public interface Server extends PluginMessageRecipient {
* @param save whether to save the chunks before unloading
* @return true if successful, false otherwise
*/
public boolean unloadWorld(World world, boolean save);
public boolean unloadWorld(@NotNull World world, boolean save);
/**
* Gets the world with the given name.
@ -415,7 +438,8 @@ public interface Server extends PluginMessageRecipient {
* @param name the name of the world to retrieve
* @return a world with the given name, or null if none exists
*/
public World getWorld(String name);
@Nullable
public World getWorld(@NotNull String name);
/**
* Gets the world from the given Unique ID.
@ -423,7 +447,8 @@ public interface Server extends PluginMessageRecipient {
* @param uid a unique-id of the world to retrieve
* @return a world with the given Unique ID, or null if none exists
*/
public World getWorld(UUID uid);
@Nullable
public World getWorld(@NotNull UUID uid);
/**
* Gets the map from the given item ID.
@ -433,6 +458,7 @@ public interface Server extends PluginMessageRecipient {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public MapView getMap(int id);
/**
@ -441,7 +467,8 @@ public interface Server extends PluginMessageRecipient {
* @param world the world the map will belong to
* @return a newly created map view
*/
public MapView createMap(World world);
@NotNull
public MapView createMap(@NotNull World world);
/**
* Create a new explorer map targeting the closest nearby structure of a
@ -458,7 +485,8 @@ public interface Server extends PluginMessageRecipient {
* @see World#locateNearestStructure(org.bukkit.Location,
* org.bukkit.StructureType, int, boolean)
*/
public ItemStack createExplorerMap(World world, Location location, StructureType structureType);
@NotNull
public ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType);
/**
* Create a new explorer map targeting the closest nearby structure of a
@ -478,7 +506,8 @@ public interface Server extends PluginMessageRecipient {
* @see World#locateNearestStructure(org.bukkit.Location,
* org.bukkit.StructureType, int, boolean)
*/
public ItemStack createExplorerMap(World world, Location location, StructureType structureType, int radius, boolean findUnexplored);
@NotNull
public ItemStack createExplorerMap(@NotNull World world, @NotNull Location location, @NotNull StructureType structureType, int radius, boolean findUnexplored);
/**
* Reloads the server, refreshing settings and plugin information.
@ -496,6 +525,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return Logger associated with this server
*/
@NotNull
public Logger getLogger();
/**
@ -504,7 +534,8 @@ public interface Server extends PluginMessageRecipient {
* @param name the name of the command to retrieve
* @return a plugin command if found, null otherwise
*/
public PluginCommand getPluginCommand(String name);
@Nullable
public PluginCommand getPluginCommand(@NotNull String name);
/**
* Writes loaded players to disk.
@ -521,7 +552,7 @@ public interface Server extends PluginMessageRecipient {
* @throws CommandException thrown when the executor for the given command
* fails with an unhandled exception
*/
public boolean dispatchCommand(CommandSender sender, String commandLine) throws CommandException;
public boolean dispatchCommand(@NotNull CommandSender sender, @NotNull String commandLine) throws CommandException;
/**
* Adds a recipe to the crafting manager.
@ -530,7 +561,8 @@ public interface Server extends PluginMessageRecipient {
* @return true if the recipe was added, false if it wasn't for some
* reason
*/
public boolean addRecipe(Recipe recipe);
@Contract("null -> false")
public boolean addRecipe(@Nullable Recipe recipe);
/**
* Get a list of all recipes for a given item. The stack size is ignored
@ -539,13 +571,15 @@ public interface Server extends PluginMessageRecipient {
* @param result the item to match against recipe results
* @return a list of recipes with the given result
*/
public List<Recipe> getRecipesFor(ItemStack result);
@NotNull
public List<Recipe> getRecipesFor(@NotNull ItemStack result);
/**
* Get an iterator through the list of crafting recipes.
*
* @return an iterator
*/
@NotNull
public Iterator<Recipe> recipeIterator();
/**
@ -563,6 +597,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a map of aliases to command names
*/
@NotNull
public Map<String, String[]> getCommandAliases();
/**
@ -614,7 +649,7 @@ public interface Server extends PluginMessageRecipient {
* permissibles} must have to receive the broadcast
* @return number of message recipients
*/
public int broadcast(String message, String permission);
public int broadcast(@NotNull String message, @NotNull String permission);
/**
* Gets the player by the given name, regardless if they are offline or
@ -633,7 +668,8 @@ public interface Server extends PluginMessageRecipient {
* @see #getOfflinePlayer(java.util.UUID)
*/
@Deprecated
public OfflinePlayer getOfflinePlayer(String name);
@NotNull
public OfflinePlayer getOfflinePlayer(@NotNull String name);
/**
* Gets the player by the given UUID, regardless if they are offline or
@ -645,13 +681,15 @@ public interface Server extends PluginMessageRecipient {
* @param id the UUID of the player to retrieve
* @return an offline player
*/
public OfflinePlayer getOfflinePlayer(UUID id);
@NotNull
public OfflinePlayer getOfflinePlayer(@NotNull UUID id);
/**
* Gets a set containing all current IPs that are banned.
*
* @return a set containing banned IP addresses
*/
@NotNull
public Set<String> getIPBans();
/**
@ -659,20 +697,21 @@ public interface Server extends PluginMessageRecipient {
*
* @param address the IP address to ban
*/
public void banIP(String address);
public void banIP(@NotNull String address);
/**
* Unbans the specified address from the server.
*
* @param address the IP address to unban
*/
public void unbanIP(String address);
public void unbanIP(@NotNull String address);
/**
* Gets a set containing all banned players.
*
* @return a set containing banned players
*/
@NotNull
public Set<OfflinePlayer> getBannedPlayers();
/**
@ -684,13 +723,15 @@ public interface Server extends PluginMessageRecipient {
* @param type the type of list to fetch, cannot be null
* @return a ban list of the specified type
*/
public BanList getBanList(BanList.Type type);
@NotNull
public BanList getBanList(@NotNull BanList.Type type);
/**
* Gets a set containing all player operators.
*
* @return a set containing player operators
*/
@NotNull
public Set<OfflinePlayer> getOperators();
/**
@ -698,6 +739,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the default game mode
*/
@NotNull
public GameMode getDefaultGameMode();
/**
@ -705,7 +747,7 @@ public interface Server extends PluginMessageRecipient {
*
* @param mode the new game mode
*/
public void setDefaultGameMode(GameMode mode);
public void setDefaultGameMode(@NotNull GameMode mode);
/**
* Gets a {@link ConsoleCommandSender} that may be used as an input source
@ -713,6 +755,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a console command sender
*/
@NotNull
public ConsoleCommandSender getConsoleSender();
/**
@ -720,6 +763,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return folder that contains all worlds
*/
@NotNull
public File getWorldContainer();
/**
@ -727,6 +771,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return an array containing all previous players
*/
@NotNull
public OfflinePlayer[] getOfflinePlayers();
/**
@ -734,6 +779,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return messenger responsible for this server
*/
@NotNull
public Messenger getMessenger();
/**
@ -741,6 +787,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a help map for this server
*/
@NotNull
public HelpMap getHelpMap();
/**
@ -766,7 +813,8 @@ public interface Server extends PluginMessageRecipient {
*
* @see InventoryType#isCreatable()
*/
Inventory createInventory(InventoryHolder owner, InventoryType type);
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, @NotNull InventoryType type);
/**
* Creates an empty inventory with the specified type and title. If the type
@ -792,7 +840,8 @@ public interface Server extends PluginMessageRecipient {
*
* @see InventoryType#isCreatable()
*/
Inventory createInventory(InventoryHolder owner, InventoryType type, String title);
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, @NotNull InventoryType type, @NotNull String title);
/**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the
@ -803,7 +852,8 @@ public interface Server extends PluginMessageRecipient {
* @return a new inventory
* @throws IllegalArgumentException if the size is not a multiple of 9
*/
Inventory createInventory(InventoryHolder owner, int size) throws IllegalArgumentException;
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, int size) throws IllegalArgumentException;
/**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the
@ -816,7 +866,8 @@ public interface Server extends PluginMessageRecipient {
* @return a new inventory
* @throws IllegalArgumentException if the size is not a multiple of 9
*/
Inventory createInventory(InventoryHolder owner, int size, String title) throws IllegalArgumentException;
@NotNull
Inventory createInventory(@Nullable InventoryHolder owner, int size, @NotNull String title) throws IllegalArgumentException;
/**
* Creates an empty merchant.
@ -825,7 +876,8 @@ public interface Server extends PluginMessageRecipient {
* when the merchant inventory is viewed
* @return a new merchant
*/
Merchant createMerchant(String title);
@NotNull
Merchant createMerchant(@Nullable String title);
/**
* Gets user-specified limit for number of monsters that can spawn in a
@ -878,6 +930,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the servers MOTD
*/
@NotNull
String getMotd();
/**
@ -885,6 +938,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the shutdown message
*/
@Nullable
String getShutdownMessage();
/**
@ -892,6 +946,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the configured warning state
*/
@NotNull
public WarningState getWarningState();
/**
@ -900,6 +955,7 @@ public interface Server extends PluginMessageRecipient {
* @return the item factory
* @see ItemFactory
*/
@NotNull
ItemFactory getItemFactory();
/**
@ -909,6 +965,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return the scoreboard manager or null if no worlds are loaded.
*/
@Nullable
ScoreboardManager getScoreboardManager();
/**
@ -918,6 +975,7 @@ public interface Server extends PluginMessageRecipient {
* implementation to indicate no defined icon, but this behavior is
* not guaranteed
*/
@Nullable
CachedServerIcon getServerIcon();
/**
@ -934,7 +992,8 @@ public interface Server extends PluginMessageRecipient {
* @return a cached server-icon that can be used for a {@link
* ServerListPingEvent#setServerIcon(CachedServerIcon)}
*/
CachedServerIcon loadServerIcon(File file) throws IllegalArgumentException, Exception;
@NotNull
CachedServerIcon loadServerIcon(@NotNull File file) throws IllegalArgumentException, Exception;
/**
* Creates a cached server-icon for the specific image.
@ -949,7 +1008,8 @@ public interface Server extends PluginMessageRecipient {
* @return a cached server-icon that can be used for a {@link
* ServerListPingEvent#setServerIcon(CachedServerIcon)}
*/
CachedServerIcon loadServerIcon(BufferedImage image) throws IllegalArgumentException, Exception;
@NotNull
CachedServerIcon loadServerIcon(@NotNull BufferedImage image) throws IllegalArgumentException, Exception;
/**
* Set the idle kick timeout. Any players idle for the specified amount of
@ -977,7 +1037,8 @@ public interface Server extends PluginMessageRecipient {
* @return a new ChunkData for the world
*
*/
public ChunkGenerator.ChunkData createChunkData(World world);
@NotNull
public ChunkGenerator.ChunkData createChunkData(@NotNull World world);
/**
* Creates a boss bar instance to display to players. The progress
@ -989,7 +1050,8 @@ public interface Server extends PluginMessageRecipient {
* @param flags an optional list of flags to set on the boss bar
* @return the created boss bar
*/
BossBar createBossBar(String title, BarColor color, BarStyle style, BarFlag... flags);
@NotNull
BossBar createBossBar(@Nullable String title, @NotNull BarColor color, @NotNull BarStyle style, @NotNull BarFlag... flags);
/**
* Creates a boss bar instance to display to players. The progress defaults
@ -1005,7 +1067,8 @@ public interface Server extends PluginMessageRecipient {
* @param flags an optional list of flags to set on the boss bar
* @return the created boss bar
*/
KeyedBossBar createBossBar(NamespacedKey key, String title, BarColor color, BarStyle style, BarFlag... flags);
@NotNull
KeyedBossBar createBossBar(@NotNull NamespacedKey key, @Nullable String title, @NotNull BarColor color, @NotNull BarStyle style, @NotNull BarFlag... flags);
/**
* Gets an unmodifiable iterator through all persistent bossbars.
@ -1021,6 +1084,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return a bossbar iterator
*/
@NotNull
Iterator<KeyedBossBar> getBossBars();
/**
@ -1038,7 +1102,8 @@ public interface Server extends PluginMessageRecipient {
* @param key unique bossbar key
* @return bossbar or null if not exists
*/
KeyedBossBar getBossBar(NamespacedKey key);
@Nullable
KeyedBossBar getBossBar(@NotNull NamespacedKey key);
/**
* Removes a {@link KeyedBossBar} specified by this key.
@ -1055,7 +1120,7 @@ public interface Server extends PluginMessageRecipient {
* @param key unique bossbar key
* @return true if removal succeeded or false
*/
boolean removeBossBar(NamespacedKey key);
boolean removeBossBar(@NotNull NamespacedKey key);
/**
* Gets an entity on the server by its UUID
@ -1063,7 +1128,8 @@ public interface Server extends PluginMessageRecipient {
* @param uuid the UUID of the entity
* @return the entity with the given UUID, or null if it isn't found
*/
Entity getEntity(UUID uuid);
@Nullable
Entity getEntity(@NotNull UUID uuid);
/**
* Get the advancement specified by this key.
@ -1071,7 +1137,8 @@ public interface Server extends PluginMessageRecipient {
* @param key unique advancement key
* @return advancement or null if not exists
*/
Advancement getAdvancement(NamespacedKey key);
@Nullable
Advancement getAdvancement(@NotNull NamespacedKey key);
/**
* Get an iterator through all advancements. Advancements cannot be removed
@ -1079,6 +1146,7 @@ public interface Server extends PluginMessageRecipient {
*
* @return an advancement iterator
*/
@NotNull
Iterator<Advancement> advancementIterator();
/**
@ -1088,7 +1156,8 @@ public interface Server extends PluginMessageRecipient {
* @param material the material
* @return new data instance
*/
BlockData createBlockData(Material material);
@NotNull
BlockData createBlockData(@NotNull Material material);
/**
* Creates a new {@link BlockData} instance for the specified Material, with
@ -1098,7 +1167,8 @@ public interface Server extends PluginMessageRecipient {
* @param consumer consumer to run on new instance before returning
* @return new data instance
*/
public BlockData createBlockData(Material material, Consumer<BlockData> consumer);
@NotNull
public BlockData createBlockData(@NotNull Material material, @Nullable Consumer<BlockData> consumer);
/**
* Creates a new {@link BlockData} instance with material and properties
@ -1108,7 +1178,8 @@ public interface Server extends PluginMessageRecipient {
* @return new data instance
* @throws IllegalArgumentException if the specified data is not valid
*/
BlockData createBlockData(String data) throws IllegalArgumentException;
@NotNull
BlockData createBlockData(@NotNull String data) throws IllegalArgumentException;
/**
* Creates a new {@link BlockData} instance for the specified Material, with
@ -1123,7 +1194,9 @@ public interface Server extends PluginMessageRecipient {
* @return new data instance
* @throws IllegalArgumentException if the specified data is not valid
*/
BlockData createBlockData(Material material, String data) throws IllegalArgumentException;
@NotNull
@Contract("null, null -> fail")
BlockData createBlockData(@Nullable Material material, @Nullable String data) throws IllegalArgumentException;
/**
* Gets a tag which has already been defined within the server. Plugins are
@ -1143,7 +1216,8 @@ public interface Server extends PluginMessageRecipient {
* @param clazz the class of the tag entries
* @return the tag or null
*/
<T extends Keyed> Tag<T> getTag(String registry, NamespacedKey tag, Class<T> clazz);
@Nullable
<T extends Keyed> Tag<T> getTag(@NotNull String registry, @NotNull NamespacedKey tag, @NotNull Class<T> clazz);
/**
* Gets a all tags which have been defined within the server.
@ -1158,7 +1232,8 @@ public interface Server extends PluginMessageRecipient {
* @param clazz the class of the tag entries
* @return all defined tags
*/
<T extends Keyed> Iterable<Tag<T>> getTags(String registry, Class<T> clazz);
@NotNull
<T extends Keyed> Iterable<Tag<T>> getTags(@NotNull String registry, @NotNull Class<T> clazz);
/**
* Gets the specified {@link LootTable}.
@ -1166,7 +1241,8 @@ public interface Server extends PluginMessageRecipient {
* @param key the name of the LootTable
* @return the LootTable, or null if no LootTable is found with that name
*/
LootTable getLootTable(NamespacedKey key);
@Nullable
LootTable getLootTable(@NotNull NamespacedKey key);
/**
* Selects entities using the given Vanilla selector.
@ -1190,12 +1266,14 @@ public interface Server extends PluginMessageRecipient {
* @deprecated draft API
*/
@Deprecated
List<Entity> selectEntities(CommandSender sender, String selector) throws IllegalArgumentException;
@NotNull
List<Entity> selectEntities(@NotNull CommandSender sender, @NotNull String selector) throws IllegalArgumentException;
/**
* @see UnsafeValues
* @return the unsafe values instance
*/
@Deprecated
@NotNull
UnsafeValues getUnsafe();
}

5
paper-api/src/main/java/org/bukkit/Statistic.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
/**
* Represents a countable statistic, which is tracked by the server.
*/
@ -80,7 +82,7 @@ public enum Statistic {
this(Type.UNTYPED);
}
private Statistic(Type type) {
private Statistic(@NotNull Type type) {
this.type = type;
}
@ -89,6 +91,7 @@ public enum Statistic {
*
* @return the type of this statistic
*/
@NotNull
public Type getType() {
return type;
}

10
paper-api/src/main/java/org/bukkit/StructureType.java
View File

@ -4,6 +4,8 @@ import com.google.common.base.Preconditions;
import com.google.common.collect.ImmutableMap;
import org.apache.commons.lang.Validate;
import org.bukkit.map.MapCursor;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.HashMap;
import java.util.Map;
@ -153,7 +155,7 @@ public class StructureType {
* when creating explorer maps. Use null to indicate this structure should
* not be compatible with explorer maps.
*/
private StructureType(String name, MapCursor.Type mapIcon) {
private StructureType(@NotNull String name, @Nullable MapCursor.Type mapIcon) {
Validate.notEmpty(name, "Structure name cannot be empty");
this.name = name;
this.mapCursor = mapIcon;
@ -165,6 +167,7 @@ public class StructureType {
*
* @return the name of this structure
*/
@NotNull
public String getName() {
return name;
}
@ -175,6 +178,7 @@ public class StructureType {
*
* @return the {@link org.bukkit.map.MapCursor.Type} or null.
*/
@Nullable
public MapCursor.Type getMapIcon() {
return mapCursor;
}
@ -204,7 +208,8 @@ public class StructureType {
return "StructureType{name=" + this.name + ", cursor=" + this.mapCursor + "}";
}
private static <T extends StructureType> T register(T type) {
@NotNull
private static <T extends StructureType> T register(@NotNull T type) {
Preconditions.checkNotNull(type, "Cannot register null StructureType.");
Preconditions.checkArgument(!structureTypeMap.containsKey(type.getName()), "Cannot register same StructureType twice. %s", type.getName());
StructureType.structureTypeMap.put(type.getName(), type);
@ -216,6 +221,7 @@ public class StructureType {
*
* @return an immutable copy of registered structure types.
*/
@NotNull
public static Map<String, StructureType> getStructureTypes() {
return ImmutableMap.copyOf(structureTypeMap);
}

5
paper-api/src/main/java/org/bukkit/Tag.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
import java.util.Set;
/**
@ -196,13 +198,14 @@ public interface Tag<T extends Keyed> extends Keyed {
* @param item to check
* @return if it is tagged
*/
boolean isTagged(T item);
boolean isTagged(@NotNull T item);
/**
* Gets an immutable set of all tagged items.
*
* @return set of tagged items
*/
@NotNull
Set<T> getValues();
}

12
paper-api/src/main/java/org/bukkit/TravelAgent.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
/**
* The Travel Agent handles the creation and the research of Nether and End
* portals when Entities try to use one.
@ -17,6 +19,7 @@ public interface TravelAgent {
* location
* @return this travel agent
*/
@NotNull
public TravelAgent setSearchRadius(int radius);
/**
@ -32,6 +35,7 @@ public interface TravelAgent {
* @param radius the radius in which to create a portal from the location
* @return this travel agent
*/
@NotNull
public TravelAgent setCreationRadius(int radius);
/**
@ -68,7 +72,8 @@ public interface TravelAgent {
* location passed to the method if unsuccessful
* @see #createPortal(Location)
*/
public Location findOrCreate(Location location);
@NotNull
public Location findOrCreate(@NotNull Location location);
/**
* Attempt to find a portal near the given location.
@ -76,7 +81,8 @@ public interface TravelAgent {
* @param location the desired location of the portal
* @return the location of the nearest portal to the location
*/
public Location findPortal(Location location);
@NotNull
public Location findPortal(@NotNull Location location);
/**
* Attempt to create a portal near the given location.
@ -90,5 +96,5 @@ public interface TravelAgent {
* @param location the desired location of the portal
* @return true if a portal was successfully created
*/
public boolean createPortal(Location location);
public boolean createPortal(@NotNull Location location);
}

2
paper-api/src/main/java/org/bukkit/TreeSpecies.java
View File

@ -3,6 +3,7 @@ package org.bukkit;
import java.util.Map;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.Nullable;
/**
* Represents the different species of trees regardless of size.
@ -62,6 +63,7 @@ public enum TreeSpecies {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static TreeSpecies getByData(final byte data) {
return BY_DATA.get(data);
}

26
paper-api/src/main/java/org/bukkit/UndefinedNullability.java Normal file
View File

@ -0,0 +1,26 @@
package org.bukkit;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Annotation for types, whose nullability is not well defined, so
* {@link org.jetbrains.annotations.NotNull} nor
* {@link org.jetbrains.annotations.Nullable} is applicable. For example when
* interface defines a method, whose nullability depends on the implementation.
*
* @deprecated This should generally not be used in any new API code as it
* suggests a bad API design.
*/
@Retention(RetentionPolicy.CLASS)
@Deprecated
public @interface UndefinedNullability {
/**
* Human readable description of the circumstances, in which the type is
* nullable.
*
* @return description
*/
String value() default "";
}

7
paper-api/src/main/java/org/bukkit/Warning.java
View File

@ -7,6 +7,8 @@ import java.lang.annotation.Target;
import java.util.Map;
import com.google.common.collect.ImmutableMap;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* This designates the warning state for a specific item.
@ -65,7 +67,7 @@ public @interface Warning {
* specifies false for {@link Warning#value()}, true otherwise.
* </ul>
*/
public boolean printFor(Warning warning) {
public boolean printFor(@Nullable Warning warning) {
if (this == DEFAULT) {
return warning == null || warning.value();
}
@ -80,7 +82,8 @@ public @interface Warning {
* @return {@link #DEFAULT} if not found, or the respective
* WarningState
*/
public static WarningState value(final String value) {
@NotNull
public static WarningState value(@Nullable final String value) {
if (value == null) {
return DEFAULT;
}

206
paper-api/src/main/java/org/bukkit/World.java
View File

@ -22,6 +22,9 @@ import org.bukkit.util.BoundingBox;
import org.bukkit.util.Consumer;
import org.bukkit.util.RayTraceResult;
import org.bukkit.util.Vector;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a world, which may contain entities, chunks and blocks
@ -36,6 +39,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param z Z-coordinate of the block
* @return Block at the given coordinates
*/
@NotNull
public Block getBlockAt(int x, int y, int z);
/**
@ -44,7 +48,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param location Location of the block
* @return Block at the given location
*/
public Block getBlockAt(Location location);
@NotNull
public Block getBlockAt(@NotNull Location location);
/**
* Gets the y coordinate of the lowest block at this position such that the
@ -64,7 +69,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param location Location of the blocks
* @return Y-coordinate of the highest non-air block
*/
public int getHighestBlockYAt(Location location);
public int getHighestBlockYAt(@NotNull Location location);
/**
* Gets the lowest block at the given coordinates such that the block and
@ -74,6 +79,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param z Z-coordinate of the block
* @return Highest non-empty block
*/
@NotNull
public Block getHighestBlockAt(int x, int z);
/**
@ -83,7 +89,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param location Coordinates to get the highest block
* @return Highest non-empty block
*/
public Block getHighestBlockAt(Location location);
@NotNull
public Block getHighestBlockAt(@NotNull Location location);
/**
* Gets the {@link Chunk} at the given coordinates
@ -92,6 +99,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param z Z-coordinate of the chunk
* @return Chunk at the given coordinates
*/
@NotNull
public Chunk getChunkAt(int x, int z);
/**
@ -100,7 +108,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param location Location of the chunk
* @return Chunk at the given location
*/
public Chunk getChunkAt(Location location);
@NotNull
public Chunk getChunkAt(@NotNull Location location);
/**
* Gets the {@link Chunk} that contains the given {@link Block}
@ -108,7 +117,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param block Block to get the containing chunk from
* @return The chunk that contains the given block
*/
public Chunk getChunkAt(Block block);
@NotNull
public Chunk getChunkAt(@NotNull Block block);
/**
* Checks if the specified {@link Chunk} is loaded
@ -116,13 +126,14 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param chunk The chunk to check
* @return true if the chunk is loaded, otherwise false
*/
public boolean isChunkLoaded(Chunk chunk);
public boolean isChunkLoaded(@NotNull Chunk chunk);
/**
* Gets an array of all loaded {@link Chunk}s
*
* @return Chunk[] containing all loaded chunks
*/
@NotNull
public Chunk[] getLoadedChunks();
/**
@ -130,7 +141,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @param chunk The chunk to load
*/
public void loadChunk(Chunk chunk);
public void loadChunk(@NotNull Chunk chunk);
/**
* Checks if the {@link Chunk} at the specified coordinates is loaded
@ -189,12 +200,12 @@ public interface World extends PluginMessageRecipient, Metadatable {
* Safely unloads and saves the {@link Chunk} at the specified coordinates
* <p>
* This method is analogous to {@link #unloadChunk(int, int, boolean,
* boolean)} where safe and saveis true
* boolean)} where safe and save is true
*
* @param chunk the chunk to unload
* @return true if the chunk has unloaded successfully, otherwise false
*/
public boolean unloadChunk(Chunk chunk);
public boolean unloadChunk(@NotNull Chunk chunk);
/**
* Safely unloads and saves the {@link Chunk} at the specified coordinates
@ -319,6 +330,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return unmodifiable collection of force loaded chunks
*/
@NotNull
public Collection<Chunk> getForceLoadedChunks();
/**
@ -328,7 +340,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param item ItemStack to drop
* @return ItemDrop entity created as a result of this method
*/
public Item dropItem(Location location, ItemStack item);
@NotNull
public Item dropItem(@NotNull Location location, @NotNull ItemStack item);
/**
* Drops an item at the specified {@link Location} with a random offset
@ -337,7 +350,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param item ItemStack to drop
* @return ItemDrop entity created as a result of this method
*/
public Item dropItemNaturally(Location location, ItemStack item);
@NotNull
public Item dropItemNaturally(@NotNull Location location, @NotNull ItemStack item);
/**
* Creates an {@link Arrow} entity at the given {@link Location}
@ -348,7 +362,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param spread Spread of the arrow. A recommend spread is 12
* @return Arrow entity spawned as a result of this method
*/
public Arrow spawnArrow(Location location, Vector direction, float speed, float spread);
@NotNull
public Arrow spawnArrow(@NotNull Location location, @NotNull Vector direction, float speed, float spread);
/**
* Creates an arrow entity of the given class at the given {@link Location}
@ -362,7 +377,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* {@link org.bukkit.entity.SpectralArrow},{@link org.bukkit.entity.Arrow},{@link org.bukkit.entity.TippedArrow}
* @return Arrow entity spawned as a result of this method
*/
public <T extends Arrow> T spawnArrow(Location location, Vector direction, float speed, float spread, Class<T> clazz);
@NotNull
public <T extends Arrow> T spawnArrow(@NotNull Location location, @NotNull Vector direction, float speed, float spread, @NotNull Class<T> clazz);
/**
* Creates a tree at the given {@link Location}
@ -371,7 +387,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param type Type of the tree to create
* @return true if the tree was created successfully, otherwise false
*/
public boolean generateTree(Location location, TreeType type);
public boolean generateTree(@NotNull Location location, @NotNull TreeType type);
/**
* Creates a tree at the given {@link Location}
@ -382,7 +398,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* this method
* @return true if the tree was created successfully, otherwise false
*/
public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate);
public boolean generateTree(@NotNull Location loc, @NotNull TreeType type, @NotNull BlockChangeDelegate delegate);
/**
* Creates a entity at the given {@link Location}
@ -391,7 +407,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param type The entity to spawn
* @return Resulting Entity of this method, or null if it was unsuccessful
*/
public Entity spawnEntity(Location loc, EntityType type);
@NotNull
public Entity spawnEntity(@NotNull Location loc, @NotNull EntityType type);
/**
* Strikes lightning at the given {@link Location}
@ -399,7 +416,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param loc The location to strike lightning
* @return The lightning entity.
*/
public LightningStrike strikeLightning(Location loc);
@NotNull
public LightningStrike strikeLightning(@NotNull Location loc);
/**
* Strikes lightning at the given {@link Location} without doing damage
@ -407,13 +425,15 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param loc The location to strike lightning
* @return The lightning entity.
*/
public LightningStrike strikeLightningEffect(Location loc);
@NotNull
public LightningStrike strikeLightningEffect(@NotNull Location loc);
/**
* Get a list of all entities in this World
*
* @return A List of all Entities currently residing in this world
*/
@NotNull
public List<Entity> getEntities();
/**
@ -421,6 +441,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return A List of all LivingEntities currently residing in this world
*/
@NotNull
public List<LivingEntity> getLivingEntities();
/**
@ -433,7 +454,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* match the given class/interface
*/
@Deprecated
public <T extends Entity> Collection<T> getEntitiesByClass(Class<T>... classes);
@NotNull
public <T extends Entity> Collection<T> getEntitiesByClass(@NotNull Class<T>... classes);
/**
* Get a collection of all entities in this World matching the given
@ -444,7 +466,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return A List of all Entities currently residing in this world that
* match the given class/interface
*/
public <T extends Entity> Collection<T> getEntitiesByClass(Class<T> cls);
@NotNull
public <T extends Entity> Collection<T> getEntitiesByClass(@NotNull Class<T> cls);
/**
* Get a collection of all entities in this World matching any of the
@ -454,13 +477,15 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return A List of all Entities currently residing in this world that
* match one or more of the given classes/interfaces
*/
public Collection<Entity> getEntitiesByClasses(Class<?>... classes);
@NotNull
public Collection<Entity> getEntitiesByClasses(@NotNull Class<?>... classes);
/**
* Get a list of all players in this World
*
* @return A list of all Players currently residing in this world
*/
@NotNull
public List<Player> getPlayers();
/**
@ -478,7 +503,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the collection of entities near location. This will always be a
* non-null collection.
*/
public Collection<Entity> getNearbyEntities(Location location, double x, double y, double z);
@NotNull
public Collection<Entity> getNearbyEntities(@NotNull Location location, double x, double y, double z);
/**
* Returns a list of entities within a bounding box centered around a
@ -497,7 +523,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the collection of entities near location. This will always be a
* non-null collection.
*/
public Collection<Entity> getNearbyEntities(Location location, double x, double y, double z, Predicate<Entity> filter);
@NotNull
public Collection<Entity> getNearbyEntities(@NotNull Location location, double x, double y, double z, @Nullable Predicate<Entity> filter);
/**
* Returns a list of entities within the given bounding box.
@ -510,7 +537,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the collection of entities within the bounding box, will always
* be a non-null collection
*/
public Collection<Entity> getNearbyEntities(BoundingBox boundingBox);
@NotNull
public Collection<Entity> getNearbyEntities(@NotNull BoundingBox boundingBox);
/**
* Returns a list of entities within the given bounding box.
@ -525,7 +553,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the collection of entities within the bounding box, will always
* be a non-null collection
*/
public Collection<Entity> getNearbyEntities(BoundingBox boundingBox, Predicate<Entity> filter);
@NotNull
public Collection<Entity> getNearbyEntities(@NotNull BoundingBox boundingBox, @Nullable Predicate<Entity> filter);
/**
* Performs a ray trace that checks for entity collisions.
@ -541,7 +570,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* is no hit
* @see #rayTraceEntities(Location, Vector, double, double, Predicate)
*/
public RayTraceResult rayTraceEntities(Location start, Vector direction, double maxDistance);
@Nullable
public RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance);
/**
* Performs a ray trace that checks for entity collisions.
@ -559,7 +589,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* is no hit
* @see #rayTraceEntities(Location, Vector, double, double, Predicate)
*/
public RayTraceResult rayTraceEntities(Location start, Vector direction, double maxDistance, double raySize);
@Nullable
public RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance, double raySize);
/**
* Performs a ray trace that checks for entity collisions.
@ -577,7 +608,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* is no hit
* @see #rayTraceEntities(Location, Vector, double, double, Predicate)
*/
public RayTraceResult rayTraceEntities(Location start, Vector direction, double maxDistance, Predicate<Entity> filter);
@Nullable
public RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance, @Nullable Predicate<Entity> filter);
/**
* Performs a ray trace that checks for entity collisions.
@ -596,7 +628,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the closest ray trace hit result, or <code>null</code> if there
* is no hit
*/
public RayTraceResult rayTraceEntities(Location start, Vector direction, double maxDistance, double raySize, Predicate<Entity> filter);
@Nullable
public RayTraceResult rayTraceEntities(@NotNull Location start, @NotNull Vector direction, double maxDistance, double raySize, @Nullable Predicate<Entity> filter);
/**
* Performs a ray trace that checks for block collisions using the blocks'
@ -614,7 +647,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the ray trace hit result, or <code>null</code> if there is no hit
* @see #rayTraceBlocks(Location, Vector, double, FluidCollisionMode, boolean)
*/
public RayTraceResult rayTraceBlocks(Location start, Vector direction, double maxDistance);
@Nullable
public RayTraceResult rayTraceBlocks(@NotNull Location start, @NotNull Vector direction, double maxDistance);
/**
* Performs a ray trace that checks for block collisions using the blocks'
@ -632,7 +666,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the ray trace hit result, or <code>null</code> if there is no hit
* @see #rayTraceBlocks(Location, Vector, double, FluidCollisionMode, boolean)
*/
public RayTraceResult rayTraceBlocks(Location start, Vector direction, double maxDistance, FluidCollisionMode fluidCollisionMode);
@Nullable
public RayTraceResult rayTraceBlocks(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode);
/**
* Performs a ray trace that checks for block collisions using the blocks'
@ -656,7 +691,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* blocks (ex. tall grass, signs, fluids, ..)
* @return the ray trace hit result, or <code>null</code> if there is no hit
*/
public RayTraceResult rayTraceBlocks(Location start, Vector direction, double maxDistance, FluidCollisionMode fluidCollisionMode, boolean ignorePassableBlocks);
@Nullable
public RayTraceResult rayTraceBlocks(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode, boolean ignorePassableBlocks);
/**
* Performs a ray trace that checks for both block and entity collisions.
@ -688,13 +724,15 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the closest ray trace hit result with either a block or an
* entity, or <code>null</code> if there is no hit
*/
public RayTraceResult rayTrace(Location start, Vector direction, double maxDistance, FluidCollisionMode fluidCollisionMode, boolean ignorePassableBlocks, double raySize, Predicate<Entity> filter);
@Nullable
public RayTraceResult rayTrace(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode, boolean ignorePassableBlocks, double raySize, @Nullable Predicate<Entity> filter);
/**
* Gets the unique name of this world
*
* @return Name of this world
*/
@NotNull
public String getName();
/**
@ -702,6 +740,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return Unique ID of this world.
*/
@NotNull
public UUID getUID();
/**
@ -709,6 +748,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return The spawn location of this world
*/
@NotNull
public Location getSpawnLocation();
/**
@ -719,7 +759,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param location The {@link Location} to set the spawn for this world at.
* @return True if it was successfully set.
*/
public boolean setSpawnLocation(Location location);
@NotNull
public boolean setSpawnLocation(@NotNull Location location);
/**
* Sets the spawn location of the world
@ -877,7 +918,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param power The power of explosion, where 4F is TNT
* @return false if explosion was canceled, otherwise true
*/
public boolean createExplosion(Location loc, float power);
public boolean createExplosion(@NotNull Location loc, float power);
/**
* Creates explosion at given coordinates with given power and optionally
@ -888,13 +929,14 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param setFire Whether or not to set blocks on fire
* @return false if explosion was canceled, otherwise true
*/
public boolean createExplosion(Location loc, float power, boolean setFire);
public boolean createExplosion(@NotNull Location loc, float power, boolean setFire);
/**
* Gets the {@link Environment} type of this world
*
* @return This worlds Environment type
*/
@NotNull
public Environment getEnvironment();
/**
@ -923,6 +965,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return ChunkGenerator associated with this world
*/
@Nullable
public ChunkGenerator getGenerator();
/**
@ -935,6 +978,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return List containing any or none BlockPopulators
*/
@NotNull
public List<BlockPopulator> getPopulators();
/**
@ -947,7 +991,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @throws IllegalArgumentException if either parameter is null or the
* {@link Entity} requested cannot be spawned
*/
public <T extends Entity> T spawn(Location location, Class<T> clazz) throws IllegalArgumentException;
@NotNull
public <T extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz) throws IllegalArgumentException;
/**
* Spawn an entity of a specific class at the given {@link Location}, with
@ -965,7 +1010,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @throws IllegalArgumentException if either parameter is null or the
* {@link Entity} requested cannot be spawned
*/
public <T extends Entity> T spawn(Location location, Class<T> clazz, Consumer<T> function) throws IllegalArgumentException;
@NotNull
public <T extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz, @Nullable Consumer<T> function) throws IllegalArgumentException;
/**
* Spawn a {@link FallingBlock} entity at the given {@link Location} of
@ -981,7 +1027,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @throws IllegalArgumentException if {@link Location} or {@link
* MaterialData} are null or {@link Material} of the {@link MaterialData} is not a block
*/
public FallingBlock spawnFallingBlock(Location location, MaterialData data) throws IllegalArgumentException;
@NotNull
public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull MaterialData data) throws IllegalArgumentException;
/**
* Spawn a {@link FallingBlock} entity at the given {@link Location} of
@ -997,7 +1044,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @throws IllegalArgumentException if {@link Location} or {@link
* BlockData} are null
*/
public FallingBlock spawnFallingBlock(Location location, BlockData data) throws IllegalArgumentException;
@NotNull
public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull BlockData data) throws IllegalArgumentException;
/**
* Spawn a {@link FallingBlock} entity at the given {@link Location} of the
@ -1016,7 +1064,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @deprecated Magic value
*/
@Deprecated
public FallingBlock spawnFallingBlock(Location location, Material material, byte data) throws IllegalArgumentException;
@NotNull
public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull Material material, byte data) throws IllegalArgumentException;
/**
* Plays an effect to all players within a default radius around a given
@ -1027,7 +1076,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param effect the {@link Effect}
* @param data a data bit needed for some effects
*/
public void playEffect(Location location, Effect effect, int data);
public void playEffect(@NotNull Location location, @NotNull Effect effect, int data);
/**
* Plays an effect to all players within a given radius around a location.
@ -1038,7 +1087,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data a data bit needed for some effects
* @param radius the radius around the location
*/
public void playEffect(Location location, Effect effect, int data, int radius);
public void playEffect(@NotNull Location location, @NotNull Effect effect, int data, int radius);
/**
* Plays an effect to all players within a default radius around a given
@ -1050,7 +1099,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param effect the {@link Effect}
* @param data a data bit needed for some effects
*/
public <T> void playEffect(Location location, Effect effect, T data);
public <T> void playEffect(@NotNull Location location, @NotNull Effect effect, @Nullable T data);
/**
* Plays an effect to all players within a given radius around a location.
@ -1062,7 +1111,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data a data bit needed for some effects
* @param radius the radius around the location
*/
public <T> void playEffect(Location location, Effect effect, T data, int radius);
public <T> void playEffect(@NotNull Location location, @NotNull Effect effect, @Nullable T data, int radius);
/**
* Get empty chunk snapshot (equivalent to all air blocks), optionally
@ -1077,6 +1126,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* raw biome temperature
* @return The empty snapshot.
*/
@NotNull
public ChunkSnapshot getEmptyChunkSnapshot(int x, int z, boolean includeBiome, boolean includeBiomeTemp);
/**
@ -1110,6 +1160,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param z Z coordinate of the block
* @return Biome of the requested block
*/
@NotNull
Biome getBiome(int x, int z);
/**
@ -1119,7 +1170,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param z Z coordinate of the block
* @param bio new Biome type for this block
*/
void setBiome(int x, int z, Biome bio);
void setBiome(int x, int z, @NotNull Biome bio);
/**
* Gets the temperature for the given block coordinates.
@ -1203,13 +1254,14 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @param difficulty the new difficulty you want to set the world to
*/
public void setDifficulty(Difficulty difficulty);
public void setDifficulty(@NotNull Difficulty difficulty);
/**
* Gets the Difficulty of the world.
*
* @return The difficulty of the world.
*/
@NotNull
public Difficulty getDifficulty();
/**
@ -1217,6 +1269,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return The folder of this world.
*/
@NotNull
public File getWorldFolder();
/**
@ -1224,6 +1277,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
*
* @return Type of this world.
*/
@Nullable
public WorldType getWorldType();
/**
@ -1425,7 +1479,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
void playSound(Location location, Sound sound, float volume, float pitch);
void playSound(@NotNull Location location, @NotNull Sound sound, float volume, float pitch);
/**
* Play a Sound at the provided Location in the World.
@ -1439,7 +1493,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param volume the volume of the sound
* @param pitch the pitch of the sound
*/
void playSound(Location location, String sound, float volume, float pitch);
void playSound(@NotNull Location location, @NotNull String sound, float volume, float pitch);
/**
* Play a Sound at the provided Location in the World.
@ -1452,7 +1506,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param volume The volume of the sound
* @param pitch The pitch of the sound
*/
void playSound(Location location, Sound sound, SoundCategory category, float volume, float pitch);
void playSound(@NotNull Location location, @NotNull Sound sound, @NotNull SoundCategory category, float volume, float pitch);
/**
* Play a Sound at the provided Location in the World.
@ -1467,13 +1521,14 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param volume the volume of the sound
* @param pitch the pitch of the sound
*/
void playSound(Location location, String sound, SoundCategory category, float volume, float pitch);
void playSound(@NotNull Location location, @NotNull String sound, @NotNull SoundCategory category, float volume, float pitch);
/**
* Get an array containing the names of all the {@link GameRule}s.
*
* @return An array of {@link GameRule} names.
*/
@NotNull
public String[] getGameRules();
/**
@ -1486,7 +1541,9 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @deprecated use {@link #getGameRuleValue(GameRule)} instead
*/
@Deprecated
public String getGameRuleValue(String rule);
@Contract("null -> null; !null -> !null")
@Nullable
public String getGameRuleValue(@Nullable String rule);
/**
* Set the specified gamerule to specified value.
@ -1502,7 +1559,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @deprecated use {@link #setGameRule(GameRule, Object)} instead.
*/
@Deprecated
public boolean setGameRuleValue(String rule, String value);
public boolean setGameRuleValue(@NotNull String rule, @NotNull String value);
/**
* Checks if string is a valid game rule
@ -1510,7 +1567,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param rule Rule to check
* @return True if rule exists
*/
public boolean isGameRule(String rule);
public boolean isGameRule(@NotNull String rule);
/**
* Get the current value for a given {@link GameRule}.
@ -1519,7 +1576,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param <T> the GameRule's type
* @return the current value
*/
public <T> T getGameRuleValue(GameRule<T> rule);
@Nullable
public <T> T getGameRuleValue(@NotNull GameRule<T> rule);
/**
* Get the default value for a given {@link GameRule}. This value is not
@ -1529,7 +1587,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param <T> the type of GameRule
* @return the default value
*/
public <T> T getGameRuleDefault(GameRule<T> rule);
@Nullable
public <T> T getGameRuleDefault(@NotNull GameRule<T> rule);
/**
* Set the given {@link GameRule}'s new value.
@ -1539,13 +1598,14 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param <T> the value type of the GameRule
* @return true if the value was successfully set
*/
public <T> boolean setGameRule(GameRule<T> rule, T newValue);
public <T> boolean setGameRule(@NotNull GameRule<T> rule, @NotNull T newValue);
/**
* Gets the world border for this world.
*
* @return The world border for this world.
*/
@NotNull
public WorldBorder getWorldBorder();
/**
@ -1556,7 +1616,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param location the location to spawn at
* @param count the number of particles
*/
public void spawnParticle(Particle particle, Location location, int count);
public void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count);
/**
* Spawns the particle (the number of times specified by count)
@ -1568,7 +1628,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param z the position on the z axis to spawn at
* @param count the number of particles
*/
public void spawnParticle(Particle particle, double x, double y, double z, int count);
public void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count);
/**
* Spawns the particle (the number of times specified by count)
@ -1580,7 +1640,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data the data to use for the particle or null,
* the type of this depends on {@link Particle#getDataType()}
*/
public <T> void spawnParticle(Particle particle, Location location, int count, T data);
public <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, @Nullable T data);
/**
@ -1595,7 +1655,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data the data to use for the particle or null,
* the type of this depends on {@link Particle#getDataType()}
*/
public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, T data);
public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, @Nullable T data);
/**
* Spawns the particle (the number of times specified by count)
@ -1610,7 +1670,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param offsetY the maximum random offset on the Y axis
* @param offsetZ the maximum random offset on the Z axis
*/
public void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ);
public void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ);
/**
* Spawns the particle (the number of times specified by count)
@ -1627,7 +1687,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param offsetY the maximum random offset on the Y axis
* @param offsetZ the maximum random offset on the Z axis
*/
public void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ);
public void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ);
/**
* Spawns the particle (the number of times specified by count)
@ -1644,7 +1704,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data the data to use for the particle or null,
* the type of this depends on {@link Particle#getDataType()}
*/
public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, T data);
public <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, @Nullable T data);
/**
* Spawns the particle (the number of times specified by count)
@ -1663,7 +1723,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data the data to use for the particle or null,
* the type of this depends on {@link Particle#getDataType()}
*/
public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, T data);
public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, @Nullable T data);
/**
* Spawns the particle (the number of times specified by count)
@ -1680,7 +1740,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param extra the extra data for this particle, depends on the
* particle used (normally speed)
*/
public void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra);
public void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra);
/**
* Spawns the particle (the number of times specified by count)
@ -1699,7 +1759,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param extra the extra data for this particle, depends on the
* particle used (normally speed)
*/
public void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra);
public void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra);
/**
* Spawns the particle (the number of times specified by count)
@ -1718,7 +1778,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data the data to use for the particle or null,
* the type of this depends on {@link Particle#getDataType()}
*/
public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
public <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data);
/**
* Spawns the particle (the number of times specified by count)
@ -1739,7 +1799,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param data the data to use for the particle or null,
* the type of this depends on {@link Particle#getDataType()}
*/
public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data);
/**
* Spawns the particle (the number of times specified by count)
@ -1761,7 +1821,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* range and encourage their client to render it regardless of
* settings
*/
public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force);
public <T> void spawnParticle(@NotNull Particle particle, @NotNull Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data, boolean force);
/**
* Spawns the particle (the number of times specified by count)
@ -1785,7 +1845,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* range and encourage their client to render it regardless of
* settings
*/
public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force);
public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data, boolean force);
/**
* Find the closest nearby structure of a given {@link StructureType}.
@ -1811,7 +1871,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @return the closest {@link Location}, or null if no structure of the
* specified type exists.
*/
public Location locateNearestStructure(Location origin, StructureType structureType, int radius, boolean findUnexplored);
@Nullable
public Location locateNearestStructure(@NotNull Location origin, @NotNull StructureType structureType, int radius, boolean findUnexplored);
/**
* Represents various map environment types that a world may be
@ -1857,6 +1918,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static Environment getEnvironment(int id) {
return lookup.get(id);
}

7
paper-api/src/main/java/org/bukkit/WorldBorder.java
View File

@ -1,5 +1,7 @@
package org.bukkit;
import org.jetbrains.annotations.NotNull;
public interface WorldBorder {
/**
@ -34,6 +36,7 @@ public interface WorldBorder {
*
* @return The current border center.
*/
@NotNull
public Location getCenter();
/**
@ -49,7 +52,7 @@ public interface WorldBorder {
*
* @param location The new location of the border center. (Only x/z used)
*/
public void setCenter(Location location);
public void setCenter(@NotNull Location location);
/**
* Gets the current border damage buffer.
@ -113,5 +116,5 @@ public interface WorldBorder {
* @param location the location to check
* @return if this location is inside the border or not
*/
public boolean isInside(Location location);
public boolean isInside(@NotNull Location location);
}

42
paper-api/src/main/java/org/bukkit/WorldCreator.java
View File

@ -4,6 +4,8 @@ import java.util.Random;
import org.bukkit.command.CommandSender;
import org.bukkit.generator.ChunkGenerator;
import org.bukkit.plugin.Plugin;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents various types of options that may be used to create a world.
@ -22,7 +24,7 @@ public class WorldCreator {
*
* @param name Name of the world that will be created
*/
public WorldCreator(String name) {
public WorldCreator(@NotNull String name) {
if (name == null) {
throw new IllegalArgumentException("World name cannot be null");
}
@ -37,7 +39,8 @@ public class WorldCreator {
* @param world World to copy options from
* @return This object, for chaining
*/
public WorldCreator copy(World world) {
@NotNull
public WorldCreator copy(@NotNull World world) {
if (world == null) {
throw new IllegalArgumentException("World cannot be null");
}
@ -55,7 +58,8 @@ public class WorldCreator {
* @param creator World creator to copy options from
* @return This object, for chaining
*/
public WorldCreator copy(WorldCreator creator) {
@NotNull
public WorldCreator copy(@NotNull WorldCreator creator) {
if (creator == null) {
throw new IllegalArgumentException("Creator cannot be null");
}
@ -72,6 +76,7 @@ public class WorldCreator {
*
* @return World name
*/
@NotNull
public String name() {
return name;
}
@ -91,6 +96,7 @@ public class WorldCreator {
* @param seed World seed
* @return This object, for chaining
*/
@NotNull
public WorldCreator seed(long seed) {
this.seed = seed;
@ -102,6 +108,7 @@ public class WorldCreator {
*
* @return World environment
*/
@NotNull
public World.Environment environment() {
return environment;
}
@ -112,7 +119,8 @@ public class WorldCreator {
* @param env World environment
* @return This object, for chaining
*/
public WorldCreator environment(World.Environment env) {
@NotNull
public WorldCreator environment(@NotNull World.Environment env) {
this.environment = env;
return this;
@ -123,6 +131,7 @@ public class WorldCreator {
*
* @return World type
*/
@NotNull
public WorldType type() {
return type;
}
@ -133,7 +142,8 @@ public class WorldCreator {
* @param type World type
* @return This object, for chaining
*/
public WorldCreator type(WorldType type) {
@NotNull
public WorldCreator type(@NotNull WorldType type) {
this.type = type;
return this;
@ -147,6 +157,7 @@ public class WorldCreator {
*
* @return Chunk generator
*/
@Nullable
public ChunkGenerator generator() {
return generator;
}
@ -160,7 +171,8 @@ public class WorldCreator {
* @param generator Chunk generator
* @return This object, for chaining
*/
public WorldCreator generator(ChunkGenerator generator) {
@NotNull
public WorldCreator generator(@Nullable ChunkGenerator generator) {
this.generator = generator;
return this;
@ -179,7 +191,8 @@ public class WorldCreator {
* @param generator Name of the generator to use, in "plugin:id" notation
* @return This object, for chaining
*/
public WorldCreator generator(String generator) {
@NotNull
public WorldCreator generator(@Nullable String generator) {
this.generator = getGeneratorForName(name, generator, Bukkit.getConsoleSender());
return this;
@ -200,7 +213,8 @@ public class WorldCreator {
* messages
* @return This object, for chaining
*/
public WorldCreator generator(String generator, CommandSender output) {
@NotNull
public WorldCreator generator(@Nullable String generator, @Nullable CommandSender output) {
this.generator = getGeneratorForName(name, generator, output);
return this;
@ -212,7 +226,8 @@ public class WorldCreator {
* @param generatorSettings The settings that should be used by the generator
* @return This object, for chaining
*/
public WorldCreator generatorSettings(String generatorSettings) {
@NotNull
public WorldCreator generatorSettings(@NotNull String generatorSettings) {
this.generatorSettings = generatorSettings;
return this;
@ -223,6 +238,7 @@ public class WorldCreator {
*
* @return The settings that should be used by the generator
*/
@NotNull
public String generatorSettings() {
return generatorSettings;
}
@ -234,6 +250,7 @@ public class WorldCreator {
* @param generate Whether to generate structures
* @return This object, for chaining
*/
@NotNull
public WorldCreator generateStructures(boolean generate) {
this.generateStructures = generate;
@ -257,6 +274,7 @@ public class WorldCreator {
*
* @return Newly created or loaded world
*/
@Nullable
public World createWorld() {
return Bukkit.createWorld(this);
}
@ -267,7 +285,8 @@ public class WorldCreator {
* @param name Name of the world to load or create
* @return Resulting WorldCreator
*/
public static WorldCreator name(String name) {
@NotNull
public static WorldCreator name(@NotNull String name) {
return new WorldCreator(name);
}
@ -287,7 +306,8 @@ public class WorldCreator {
* @param output Where to output if errors are present
* @return Resulting generator, or null
*/
public static ChunkGenerator getGeneratorForName(String world, String name, CommandSender output) {
@Nullable
public static ChunkGenerator getGeneratorForName(@NotNull String world, @Nullable String name, @Nullable CommandSender output) {
ChunkGenerator result = null;
if (world == null) {

11
paper-api/src/main/java/org/bukkit/WorldType.java
View File

@ -1,6 +1,9 @@
package org.bukkit;
import com.google.common.collect.Maps;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.Map;
/**
@ -18,7 +21,7 @@ public enum WorldType {
private final static Map<String, WorldType> BY_NAME = Maps.newHashMap();
private final String name;
private WorldType(String name) {
private WorldType(@NotNull String name) {
this.name = name;
}
@ -27,17 +30,19 @@ public enum WorldType {
*
* @return Name of this type
*/
@NotNull
public String getName() {
return name;
}
/**
* Gets a Worldtype by its name
* Gets a WorldType by its name
*
* @param name Name of the WorldType to get
* @return Requested WorldType, or null if not found
*/
public static WorldType getByName(String name) {
@Nullable
public static WorldType getByName(@NotNull String name) {
return BY_NAME.get(name.toUpperCase(java.util.Locale.ENGLISH));
}

2
paper-api/src/main/java/org/bukkit/advancement/Advancement.java
View File

@ -2,6 +2,7 @@ package org.bukkit.advancement;
import java.util.Collection;
import org.bukkit.Keyed;
import org.jetbrains.annotations.NotNull;
/**
* Represents an advancement that may be awarded to a player. This class is not
@ -14,5 +15,6 @@ public interface Advancement extends Keyed {
*
* @return a unmodifiable copy of all criteria
*/
@NotNull
Collection<String> getCriteria();
}

13
paper-api/src/main/java/org/bukkit/advancement/AdvancementProgress.java
View File

@ -1,5 +1,8 @@
package org.bukkit.advancement;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.Collection;
import java.util.Date;
@ -14,6 +17,7 @@ public interface AdvancementProgress {
*
* @return the relevant advancement
*/
@NotNull
Advancement getAdvancement();
/**
@ -30,7 +34,7 @@ public interface AdvancementProgress {
* @return true if awarded, false if criteria does not exist or already
* awarded.
*/
boolean awardCriteria(String criteria);
boolean awardCriteria(@NotNull String criteria);
/**
* Mark the specified criteria as uncompleted.
@ -38,7 +42,7 @@ public interface AdvancementProgress {
* @param criteria the criteria to mark
* @return true if removed, false if criteria does not exist or not awarded
*/
boolean revokeCriteria(String criteria);
boolean revokeCriteria(@NotNull String criteria);
/**
* Get the date the specified criteria was awarded.
@ -46,13 +50,15 @@ public interface AdvancementProgress {
* @param criteria the criteria to check
* @return date awarded or null if unawarded or criteria does not exist
*/
Date getDateAwarded(String criteria);
@Nullable
Date getDateAwarded(@NotNull String criteria);
/**
* Get the criteria which have not been awarded.
*
* @return unmodifiable copy of criteria remaining
*/
@NotNull
Collection<String> getRemainingCriteria();
/**
@ -60,5 +66,6 @@ public interface AdvancementProgress {
*
* @return unmodifiable copy of criteria awarded
*/
@NotNull
Collection<String> getAwardedCriteria();
}

6
paper-api/src/main/java/org/bukkit/attribute/Attributable.java
View File

@ -1,5 +1,8 @@
package org.bukkit.attribute;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents an object which may contain attributes.
*/
@ -12,5 +15,6 @@ public interface Attributable {
* @param attribute the attribute to get
* @return the attribute instance or null if not applicable to this object
*/
AttributeInstance getAttribute(Attribute attribute);
@Nullable
AttributeInstance getAttribute(@NotNull Attribute attribute);
}

8
paper-api/src/main/java/org/bukkit/attribute/AttributeInstance.java
View File

@ -1,5 +1,7 @@
package org.bukkit.attribute;
import org.jetbrains.annotations.NotNull;
import java.util.Collection;
/**
@ -13,6 +15,7 @@ public interface AttributeInstance {
*
* @return the attribute
*/
@NotNull
Attribute getAttribute();
/**
@ -34,6 +37,7 @@ public interface AttributeInstance {
*
* @return a copied collection of all modifiers
*/
@NotNull
Collection<AttributeModifier> getModifiers();
/**
@ -41,14 +45,14 @@ public interface AttributeInstance {
*
* @param modifier to add
*/
void addModifier(AttributeModifier modifier);
void addModifier(@NotNull AttributeModifier modifier);
/**
* Remove a modifier from this instance.
*
* @param modifier to remove
*/
void removeModifier(AttributeModifier modifier);
void removeModifier(@NotNull AttributeModifier modifier);
/**
* Get the value of this instance after all associated modifiers have been

16
paper-api/src/main/java/org/bukkit/attribute/AttributeModifier.java
View File

@ -8,6 +8,8 @@ import org.apache.commons.lang.Validate;
import org.bukkit.configuration.serialization.ConfigurationSerializable;
import org.bukkit.inventory.EquipmentSlot;
import org.bukkit.util.NumberConversions;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Concrete implementation of an attribute modifier.
@ -20,15 +22,15 @@ public class AttributeModifier implements ConfigurationSerializable {
private final Operation operation;
private final EquipmentSlot slot;
public AttributeModifier(String name, double amount, Operation operation) {
public AttributeModifier(@NotNull String name, double amount, @NotNull Operation operation) {
this(UUID.randomUUID(), name, amount, operation);
}
public AttributeModifier(UUID uuid, String name, double amount, Operation operation) {
public AttributeModifier(@NotNull UUID uuid, @NotNull String name, double amount, @NotNull Operation operation) {
this(uuid, name, amount, operation, null);
}
public AttributeModifier(UUID uuid, String name, double amount, Operation operation, EquipmentSlot slot) {
public AttributeModifier(@NotNull UUID uuid, @NotNull String name, double amount, @NotNull Operation operation, @Nullable EquipmentSlot slot) {
Validate.notNull(uuid, "UUID cannot be null");
Validate.notEmpty(name, "Name cannot be empty");
Validate.notNull(operation, "Operation cannot be null");
@ -44,6 +46,7 @@ public class AttributeModifier implements ConfigurationSerializable {
*
* @return unique id
*/
@NotNull
public UUID getUniqueId() {
return uuid;
}
@ -53,6 +56,7 @@ public class AttributeModifier implements ConfigurationSerializable {
*
* @return name
*/
@NotNull
public String getName() {
return name;
}
@ -71,6 +75,7 @@ public class AttributeModifier implements ConfigurationSerializable {
*
* @return operation
*/
@NotNull
public Operation getOperation() {
return operation;
}
@ -81,10 +86,12 @@ public class AttributeModifier implements ConfigurationSerializable {
*
* @return the slot
*/
@Nullable
public EquipmentSlot getSlot() {
return slot;
}
@NotNull
@Override
public Map<String, Object> serialize() {
Map<String, Object> data = new HashMap<String, Object>();
@ -130,7 +137,8 @@ public class AttributeModifier implements ConfigurationSerializable {
+ "}";
}
public static AttributeModifier deserialize(Map<String, Object> args) {
@NotNull
public static AttributeModifier deserialize(@NotNull Map<String, Object> args) {
if (args.containsKey("slot")) {
return new AttributeModifier(UUID.fromString((String) args.get("uuid")), (String) args.get("name"), NumberConversions.toDouble(args.get("amount")), Operation.values()[NumberConversions.toInt(args.get("operation"))], EquipmentSlot.valueOf((args.get("slot").toString().toUpperCase())));
}

13
paper-api/src/main/java/org/bukkit/block/Banner.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block;
import org.bukkit.DyeColor;
import org.bukkit.block.banner.Pattern;
import org.jetbrains.annotations.NotNull;
import java.util.List;
@ -15,6 +16,7 @@ public interface Banner extends BlockState {
*
* @return the base color
*/
@NotNull
DyeColor getBaseColor();
/**
@ -24,13 +26,14 @@ public interface Banner extends BlockState {
*
* @param color the base color
*/
void setBaseColor(DyeColor color);
void setBaseColor(@NotNull DyeColor color);
/**
* Returns a list of patterns on this banner
*
* @return the patterns
*/
@NotNull
List<Pattern> getPatterns();
/**
@ -38,7 +41,7 @@ public interface Banner extends BlockState {
*
* @param patterns the new list of patterns
*/
void setPatterns(List<Pattern> patterns);
void setPatterns(@NotNull List<Pattern> patterns);
/**
* Adds a new pattern on top of the existing
@ -46,7 +49,7 @@ public interface Banner extends BlockState {
*
* @param pattern the new pattern to add
*/
void addPattern(Pattern pattern);
void addPattern(@NotNull Pattern pattern);
/**
* Returns the pattern at the specified index
@ -54,6 +57,7 @@ public interface Banner extends BlockState {
* @param i the index
* @return the pattern
*/
@NotNull
Pattern getPattern(int i);
/**
@ -62,6 +66,7 @@ public interface Banner extends BlockState {
* @param i the index
* @return the removed pattern
*/
@NotNull
Pattern removePattern(int i);
/**
@ -70,7 +75,7 @@ public interface Banner extends BlockState {
* @param i the index
* @param pattern the new pattern
*/
void setPattern(int i, Pattern pattern);
void setPattern(int i, @NotNull Pattern pattern);
/**
* Returns the number of patterns on this

11
paper-api/src/main/java/org/bukkit/block/Beacon.java
View File

@ -6,15 +6,19 @@ import org.bukkit.entity.LivingEntity;
import org.bukkit.inventory.BeaconInventory;
import org.bukkit.potion.PotionEffect;
import org.bukkit.potion.PotionEffectType;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of a beacon.
*/
public interface Beacon extends Container, Nameable {
@NotNull
@Override
BeaconInventory getInventory();
@NotNull
@Override
BeaconInventory getSnapshotInventory();
@ -27,6 +31,7 @@ public interface Beacon extends Container, Nameable {
* @return the players in range
* @throws IllegalStateException if this block state is not placed
*/
@NotNull
Collection<LivingEntity> getEntitiesInRange();
/**
@ -43,6 +48,7 @@ public interface Beacon extends Container, Nameable {
*
* @return the primary effect or null if not set
*/
@Nullable
PotionEffect getPrimaryEffect();
/**
@ -50,13 +56,14 @@ public interface Beacon extends Container, Nameable {
*
* @param effect new primary effect
*/
void setPrimaryEffect(PotionEffectType effect);
void setPrimaryEffect(@Nullable PotionEffectType effect);
/**
* Returns the secondary effect set on the beacon.
*
* @return the secondary effect or null if no secondary effect
*/
@Nullable
PotionEffect getSecondaryEffect();
/**
@ -65,5 +72,5 @@ public interface Beacon extends Container, Nameable {
*
* @param effect desired secondary effect
*/
void setSecondaryEffect(PotionEffectType effect);
void setSecondaryEffect(@Nullable PotionEffectType effect);
}

53
paper-api/src/main/java/org/bukkit/block/Block.java
View File

@ -4,9 +4,9 @@ import java.util.Collection;
import org.bukkit.Chunk;
import org.bukkit.FluidCollisionMode;
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.World;
import org.bukkit.Location;
import org.bukkit.block.data.Bisected;
import org.bukkit.block.data.BlockData;
import org.bukkit.inventory.ItemStack;
@ -14,6 +14,9 @@ import org.bukkit.metadata.Metadatable;
import org.bukkit.util.BoundingBox;
import org.bukkit.util.RayTraceResult;
import org.bukkit.util.Vector;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a block. This is a live object, and only one Block may exist for
@ -42,6 +45,7 @@ public interface Block extends Metadatable {
*
* @return block specific data
*/
@NotNull
BlockData getBlockData();
/**
@ -52,6 +56,7 @@ public interface Block extends Metadatable {
* @param modZ Z-coordinate offset
* @return Block at the given offsets
*/
@NotNull
Block getRelative(int modX, int modY, int modZ);
/**
@ -63,7 +68,8 @@ public interface Block extends Metadatable {
* @return Block at the given face
* @see #getRelative(BlockFace, int)
*/
Block getRelative(BlockFace face);
@NotNull
Block getRelative(@NotNull BlockFace face);
/**
* Gets the block at the given distance of the given face
@ -81,13 +87,15 @@ public interface Block extends Metadatable {
* @param distance Distance to get the block at
* @return Block at the given face
*/
Block getRelative(BlockFace face, int distance);
@NotNull
Block getRelative(@NotNull BlockFace face, int distance);
/**
* Gets the type of this block
*
* @return block type
*/
@NotNull
Material getType();
/**
@ -121,6 +129,7 @@ public interface Block extends Metadatable {
*
* @return World containing this block
*/
@NotNull
World getWorld();
/**
@ -149,6 +158,7 @@ public interface Block extends Metadatable {
*
* @return Location of block
*/
@NotNull
Location getLocation();
/**
@ -160,13 +170,16 @@ public interface Block extends Metadatable {
* @param loc the location to copy into
* @return The Location object provided or null
*/
Location getLocation(Location loc);
@Contract("null -> null; !null -> !null")
@Nullable
Location getLocation(@Nullable Location loc);
/**
* Gets the chunk which contains this block
*
* @return Containing Chunk
*/
@NotNull
Chunk getChunk();
/**
@ -174,7 +187,7 @@ public interface Block extends Metadatable {
*
* @param data new block specific data
*/
void setBlockData(BlockData data);
void setBlockData(@NotNull BlockData data);
/**
* Sets the complete data for this block
@ -195,14 +208,14 @@ public interface Block extends Metadatable {
* @param data new block specific data
* @param applyPhysics false to cancel physics from the changed block
*/
void setBlockData(BlockData data, boolean applyPhysics);
void setBlockData(@NotNull BlockData data, boolean applyPhysics);
/**
* Sets the type of this block
*
* @param type Material to change this block to
*/
void setType(Material type);
void setType(@NotNull Material type);
/**
* Sets the type of this block
@ -223,7 +236,7 @@ public interface Block extends Metadatable {
* @param type Material to change this block to
* @param applyPhysics False to cancel physics on the changed block.
*/
void setType(Material type, boolean applyPhysics);
void setType(@NotNull Material type, boolean applyPhysics);
/**
* Gets the face relation of this block compared to the given block.
@ -241,7 +254,8 @@ public interface Block extends Metadatable {
* @param block Block to compare against this block
* @return BlockFace of this block which has the requested block, or null
*/
BlockFace getFace(Block block);
@Nullable
BlockFace getFace(@NotNull Block block);
/**
* Captures the current state of this block. You may then cast that state
@ -252,6 +266,7 @@ public interface Block extends Metadatable {
*
* @return BlockState with the current state of this block.
*/
@NotNull
BlockState getState();
/**
@ -259,6 +274,7 @@ public interface Block extends Metadatable {
*
* @return Biome type containing this block
*/
@NotNull
Biome getBiome();
/**
@ -266,7 +282,7 @@ public interface Block extends Metadatable {
*
* @param bio new Biome type for this block
*/
void setBiome(Biome bio);
void setBiome(@NotNull Biome bio);
/**
* Returns true if the block is being powered by Redstone.
@ -288,7 +304,7 @@ public interface Block extends Metadatable {
* @param face The block face
* @return True if the block face is powered.
*/
boolean isBlockFacePowered(BlockFace face);
boolean isBlockFacePowered(@NotNull BlockFace face);
/**
* Returns true if the block face is being indirectly powered by Redstone.
@ -296,7 +312,7 @@ public interface Block extends Metadatable {
* @param face The block face
* @return True if the block face is indirectly powered.
*/
boolean isBlockFaceIndirectlyPowered(BlockFace face);
boolean isBlockFaceIndirectlyPowered(@NotNull BlockFace face);
/**
* Returns the redstone power being provided to this block face
@ -305,7 +321,7 @@ public interface Block extends Metadatable {
* block itself
* @return The power level.
*/
int getBlockPower(BlockFace face);
int getBlockPower(@NotNull BlockFace face);
/**
* Returns the redstone power being provided to this block
@ -356,6 +372,7 @@ public interface Block extends Metadatable {
*
* @return reaction
*/
@NotNull
PistonMoveReaction getPistonMoveReaction();
/**
@ -372,13 +389,14 @@ public interface Block extends Metadatable {
* @param tool The tool or item in hand used for digging
* @return true if the block was destroyed
*/
boolean breakNaturally(ItemStack tool);
boolean breakNaturally(@NotNull ItemStack tool);
/**
* Returns a list of items which would drop by destroying this block
*
* @return a list of dropped items for this type of block
*/
@NotNull
Collection<ItemStack> getDrops();
/**
@ -388,7 +406,8 @@ public interface Block extends Metadatable {
* @param tool The tool or item in hand used for digging
* @return a list of dropped items for this type of block
*/
Collection<ItemStack> getDrops(ItemStack tool);
@NotNull
Collection<ItemStack> getDrops(@NotNull ItemStack tool);
/**
* Checks if this block is passable.
@ -414,7 +433,8 @@ public interface Block extends Metadatable {
* @param fluidCollisionMode the fluid collision mode
* @return the ray trace hit result, or <code>null</code> if there is no hit
*/
RayTraceResult rayTrace(Location start, Vector direction, double maxDistance, FluidCollisionMode fluidCollisionMode);
@Nullable
RayTraceResult rayTrace(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode);
/**
* Gets the approximate bounding box for this block.
@ -430,5 +450,6 @@ public interface Block extends Metadatable {
*
* @return the approximate bounding box of the block
*/
@NotNull
BoundingBox getBoundingBox();
}

3
paper-api/src/main/java/org/bukkit/block/BlockFace.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block;
import org.bukkit.util.Vector;
import org.jetbrains.annotations.NotNull;
/**
* Represents the face of a block
@ -74,6 +75,7 @@ public enum BlockFace {
*
* @return the normal vector
*/
@NotNull
public Vector getDirection() {
Vector direction = new Vector(modX, modY, modZ);
if (modX != 0 || modY != 0 || modZ != 0) {
@ -82,6 +84,7 @@ public enum BlockFace {
return direction;
}
@NotNull
public BlockFace getOppositeFace() {
switch (this) {
case NORTH:

20
paper-api/src/main/java/org/bukkit/block/BlockState.java
View File

@ -7,6 +7,9 @@ import org.bukkit.World;
import org.bukkit.block.data.BlockData;
import org.bukkit.material.MaterialData;
import org.bukkit.metadata.Metadatable;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of a block, which will not change
@ -25,6 +28,7 @@ public interface BlockState extends Metadatable {
* @return the block represented by this block state
* @throws IllegalStateException if this block state is not placed
*/
@NotNull
Block getBlock();
/**
@ -32,6 +36,7 @@ public interface BlockState extends Metadatable {
*
* @return block specific metadata
*/
@NotNull
MaterialData getData();
/**
@ -39,6 +44,7 @@ public interface BlockState extends Metadatable {
*
* @return block specific data
*/
@NotNull
BlockData getBlockData();
/**
@ -46,6 +52,7 @@ public interface BlockState extends Metadatable {
*
* @return block type
*/
@NotNull
Material getType();
/**
@ -62,6 +69,7 @@ public interface BlockState extends Metadatable {
* @return the world containing the block represented by this block state
* @throws IllegalStateException if this block state is not placed
*/
@NotNull
World getWorld();
/**
@ -92,6 +100,7 @@ public interface BlockState extends Metadatable {
*
* @return the location
*/
@NotNull
Location getLocation();
/**
@ -105,7 +114,9 @@ public interface BlockState extends Metadatable {
* @param loc the location to copy into
* @return The Location object provided or null
*/
Location getLocation(Location loc);
@Contract("null -> null; !null -> !null")
@Nullable
Location getLocation(@Nullable Location loc);
/**
* Gets the chunk which contains the block represented by this block state.
@ -113,6 +124,7 @@ public interface BlockState extends Metadatable {
* @return the containing Chunk
* @throws IllegalStateException if this block state is not placed
*/
@NotNull
Chunk getChunk();
/**
@ -120,21 +132,21 @@ public interface BlockState extends Metadatable {
*
* @param data New block specific metadata
*/
void setData(MaterialData data);
void setData(@NotNull MaterialData data);
/**
* Sets the data for this block state.
*
* @param data New block specific data
*/
void setBlockData(BlockData data);
void setBlockData(@NotNull BlockData data);
/**
* Sets the type of this block state.
*
* @param type Material to change this block state to
*/
void setType(Material type);
void setType(@NotNull Material type);
/**
* Attempts to update the block represented by this state, setting it to

3
paper-api/src/main/java/org/bukkit/block/BrewingStand.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block;
import org.bukkit.Nameable;
import org.bukkit.inventory.BrewerInventory;
import org.jetbrains.annotations.NotNull;
/**
* Represents a captured state of a brewing stand.
@ -36,9 +37,11 @@ public interface BrewingStand extends Container, Nameable {
*/
void setFuelLevel(int level);
@NotNull
@Override
BrewerInventory getInventory();
@NotNull
@Override
BrewerInventory getSnapshotInventory();
}

2
paper-api/src/main/java/org/bukkit/block/Chest.java
View File

@ -3,6 +3,7 @@ package org.bukkit.block;
import org.bukkit.Nameable;
import org.bukkit.inventory.Inventory;
import org.bukkit.loot.Lootable;
import org.jetbrains.annotations.NotNull;
/**
* Represents a captured state of a chest.
@ -23,5 +24,6 @@ public interface Chest extends Container, Nameable, Lootable {
*
* @return the inventory
*/
@NotNull
Inventory getBlockInventory();
}

9
paper-api/src/main/java/org/bukkit/block/CommandBlock.java
View File

@ -1,5 +1,8 @@
package org.bukkit.block;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of a command block.
*/
@ -12,6 +15,7 @@ public interface CommandBlock extends BlockState {
*
* @return Command that this CommandBlock will run when powered.
*/
@NotNull
public String getCommand();
/**
@ -21,7 +25,7 @@ public interface CommandBlock extends BlockState {
*
* @param command Command that this CommandBlock will run when powered.
*/
public void setCommand(String command);
public void setCommand(@Nullable String command);
/**
* Gets the name of this CommandBlock. The name is used with commands
@ -30,6 +34,7 @@ public interface CommandBlock extends BlockState {
*
* @return Name of this CommandBlock.
*/
@NotNull
public String getName();
/**
@ -39,5 +44,5 @@ public interface CommandBlock extends BlockState {
*
* @param name New name for this CommandBlock.
*/
public void setName(String name);
public void setName(@Nullable String name);
}

3
paper-api/src/main/java/org/bukkit/block/Container.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block;
import org.bukkit.inventory.Inventory;
import org.bukkit.inventory.InventoryHolder;
import org.jetbrains.annotations.NotNull;
/**
* Represents a captured state of a container block.
@ -19,6 +20,7 @@ public interface Container extends BlockState, InventoryHolder, Lockable {
*
* @return the inventory
*/
@NotNull
@Override
Inventory getInventory();
@ -32,5 +34,6 @@ public interface Container extends BlockState, InventoryHolder, Lockable {
*
* @return the captured inventory snapshot
*/
@NotNull
Inventory getSnapshotInventory();
}

7
paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block;
import org.bukkit.entity.EntityType;
import org.jetbrains.annotations.NotNull;
/**
* Represents a captured state of a creature spawner.
@ -12,6 +13,7 @@ public interface CreatureSpawner extends BlockState {
*
* @return The creature type.
*/
@NotNull
public EntityType getSpawnedType();
/**
@ -19,7 +21,7 @@ public interface CreatureSpawner extends BlockState {
*
* @param creatureType The creature type.
*/
public void setSpawnedType(EntityType creatureType);
public void setSpawnedType(@NotNull EntityType creatureType);
/**
* Set the spawner mob type.
@ -29,7 +31,7 @@ public interface CreatureSpawner extends BlockState {
* {@link #setSpawnedType(org.bukkit.entity.EntityType)}.
*/
@Deprecated
public void setCreatureTypeByName(String creatureType);
public void setCreatureTypeByName(@NotNull String creatureType);
/**
* Get the spawner's creature type.
@ -38,6 +40,7 @@ public interface CreatureSpawner extends BlockState {
* @deprecated magic value, use {@link #getSpawnedType()}.
*/
@Deprecated
@NotNull
public String getCreatureTypeName();
/**

2
paper-api/src/main/java/org/bukkit/block/Dispenser.java
View File

@ -3,6 +3,7 @@ package org.bukkit.block;
import org.bukkit.Nameable;
import org.bukkit.loot.Lootable;
import org.bukkit.projectiles.BlockProjectileSource;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of a dispenser.
@ -18,6 +19,7 @@ public interface Dispenser extends Container, Nameable, Lootable {
* @return a BlockProjectileSource if valid, otherwise null
* @throws IllegalStateException if this block state is not placed
*/
@Nullable
public BlockProjectileSource getBlockProjectileSource();
/**

9
paper-api/src/main/java/org/bukkit/block/DoubleChest.java
View File

@ -5,6 +5,8 @@ import org.bukkit.World;
import org.bukkit.inventory.DoubleChestInventory;
import org.bukkit.inventory.Inventory;
import org.bukkit.inventory.InventoryHolder;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a double chest.
@ -12,26 +14,31 @@ import org.bukkit.inventory.InventoryHolder;
public class DoubleChest implements InventoryHolder {
private DoubleChestInventory inventory;
public DoubleChest(DoubleChestInventory chest) {
public DoubleChest(@NotNull DoubleChestInventory chest) {
inventory = chest;
}
@NotNull
public Inventory getInventory() {
return inventory;
}
@Nullable
public InventoryHolder getLeftSide() {
return inventory.getLeftSide().getHolder();
}
@Nullable
public InventoryHolder getRightSide() {
return inventory.getRightSide().getHolder();
}
@NotNull
public Location getLocation() {
return getInventory().getLocation();
}
@Nullable
public World getWorld() {
return getLocation().getWorld();
}

4
paper-api/src/main/java/org/bukkit/block/EndGateway.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block;
import org.bukkit.Location;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of an end gateway.
@ -15,6 +16,7 @@ public interface EndGateway extends BlockState {
*
* @return the gateway exit location
*/
@Nullable
Location getExitLocation();
/**
@ -26,7 +28,7 @@ public interface EndGateway extends BlockState {
* @param location the new exit location
* @throws IllegalArgumentException for differing worlds
*/
void setExitLocation(Location location);
void setExitLocation(@Nullable Location location);
/**
* Gets whether this gateway will teleport entities directly to

4
paper-api/src/main/java/org/bukkit/block/FlowerPot.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block;
import org.bukkit.material.MaterialData;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of a flower pot.
@ -14,6 +15,7 @@ public interface FlowerPot extends BlockState {
*
* @return item present, or null for empty.
*/
@Nullable
MaterialData getContents();
/**
@ -24,5 +26,5 @@ public interface FlowerPot extends BlockState {
*
* @param item new item, or null for empty.
*/
void setContents(MaterialData item);
void setContents(@Nullable MaterialData item);
}

3
paper-api/src/main/java/org/bukkit/block/Furnace.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block;
import org.bukkit.Nameable;
import org.bukkit.inventory.FurnaceInventory;
import org.jetbrains.annotations.NotNull;
/**
* Represents a captured state of a furnace.
@ -61,9 +62,11 @@ public interface Furnace extends Container, Nameable {
*/
public void setCookTimeTotal(int cookTimeTotal);
@NotNull
@Override
public FurnaceInventory getInventory();
@NotNull
@Override
public FurnaceInventory getSnapshotInventory();
}

8
paper-api/src/main/java/org/bukkit/block/Jukebox.java
View File

@ -2,6 +2,8 @@ package org.bukkit.block;
import org.bukkit.Material;
import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of a jukebox.
@ -13,6 +15,7 @@ public interface Jukebox extends BlockState {
*
* @return The record Material, or AIR if none is inserted
*/
@NotNull
public Material getPlaying();
/**
@ -20,13 +23,14 @@ public interface Jukebox extends BlockState {
*
* @param record The record Material, or null/AIR to stop playing
*/
public void setPlaying(Material record);
public void setPlaying(@Nullable Material record);
/**
* Gets the record item inserted into the jukebox.
*
* @return a copy of the inserted record, or an air stack if none
*/
@NotNull
public ItemStack getRecord();
/**
@ -34,7 +38,7 @@ public interface Jukebox extends BlockState {
*
* @param record the record to insert or null/AIR to empty
*/
public void setRecord(ItemStack record);
public void setRecord(@Nullable ItemStack record);
/**
* Checks if the jukebox is playing a record.

6
paper-api/src/main/java/org/bukkit/block/Lockable.java
View File

@ -1,5 +1,8 @@
package org.bukkit.block;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a block (usually a container) that may be locked. When a lock is
* active an item with a name corresponding to the key will be required to open
@ -19,6 +22,7 @@ public interface Lockable {
*
* @return the key needed.
*/
@NotNull
String getLock();
/**
@ -27,5 +31,5 @@ public interface Lockable {
*
* @param key the key required to access the container.
*/
void setLock(String key);
void setLock(@Nullable String key);
}

3
paper-api/src/main/java/org/bukkit/block/PistonMoveReaction.java
View File

@ -1,5 +1,7 @@
package org.bukkit.block;
import org.jetbrains.annotations.Nullable;
import java.util.HashMap;
import java.util.Map;
@ -60,6 +62,7 @@ public enum PistonMoveReaction {
* @deprecated Magic value
*/
@Deprecated
@Nullable
public static PistonMoveReaction getById(int id) {
return byId.get(id);
}

2
paper-api/src/main/java/org/bukkit/block/ShulkerBox.java
View File

@ -3,6 +3,7 @@ package org.bukkit.block;
import org.bukkit.DyeColor;
import org.bukkit.Nameable;
import org.bukkit.loot.Lootable;
import org.jetbrains.annotations.NotNull;
/**
* Represents a captured state of a ShulkerBox.
@ -14,5 +15,6 @@ public interface ShulkerBox extends Container, Nameable, Lootable {
*
* @return the {@link DyeColor} of this ShulkerBox
*/
@NotNull
public DyeColor getColor();
}

6
paper-api/src/main/java/org/bukkit/block/Sign.java
View File

@ -1,5 +1,7 @@
package org.bukkit.block;
import org.jetbrains.annotations.NotNull;
/**
* Represents a captured state of either a SignPost or a WallSign.
*/
@ -10,6 +12,7 @@ public interface Sign extends BlockState {
*
* @return Array of Strings containing each line of text
*/
@NotNull
public String[] getLines();
/**
@ -21,6 +24,7 @@ public interface Sign extends BlockState {
* @throws IndexOutOfBoundsException Thrown when the line does not exist
* @return Text on the given line
*/
@NotNull
public String getLine(int index) throws IndexOutOfBoundsException;
/**
@ -33,7 +37,7 @@ public interface Sign extends BlockState {
* @param line New text to set at the specified index
* @throws IndexOutOfBoundsException If the index is out of the range 0..3
*/
public void setLine(int index, String line) throws IndexOutOfBoundsException;
public void setLine(int index, @NotNull String line) throws IndexOutOfBoundsException;
/**
* Marks whether this sign can be edited by players.

15
paper-api/src/main/java/org/bukkit/block/Skull.java
View File

@ -4,6 +4,9 @@ import org.bukkit.Material;
import org.bukkit.OfflinePlayer;
import org.bukkit.SkullType;
import org.bukkit.block.data.BlockData;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a captured state of a skull block.
@ -24,6 +27,7 @@ public interface Skull extends BlockState {
* @deprecated See {@link #getOwningPlayer()}.
*/
@Deprecated
@Nullable
public String getOwner();
/**
@ -37,7 +41,8 @@ public interface Skull extends BlockState {
* @deprecated see {@link #setOwningPlayer(org.bukkit.OfflinePlayer)}.
*/
@Deprecated
public boolean setOwner(String name);
@Contract("null -> false")
public boolean setOwner(@Nullable String name);
/**
* Get the player which owns the skull. This player may appear as the
@ -45,6 +50,7 @@ public interface Skull extends BlockState {
*
* @return owning player
*/
@Nullable
public OfflinePlayer getOwningPlayer();
/**
@ -53,7 +59,7 @@ public interface Skull extends BlockState {
*
* @param player the owning player
*/
public void setOwningPlayer(OfflinePlayer player);
public void setOwningPlayer(@NotNull OfflinePlayer player);
/**
* Gets the rotation of the skull in the world (or facing direction if this
@ -63,6 +69,7 @@ public interface Skull extends BlockState {
* @deprecated use {@link BlockData}
*/
@Deprecated
@NotNull
public BlockFace getRotation();
/**
@ -73,7 +80,7 @@ public interface Skull extends BlockState {
* @deprecated use {@link BlockData}
*/
@Deprecated
public void setRotation(BlockFace rotation);
public void setRotation(@NotNull BlockFace rotation);
/**
* Gets the type of skull
@ -82,6 +89,7 @@ public interface Skull extends BlockState {
* @deprecated check {@link Material} instead
*/
@Deprecated
@NotNull
public SkullType getSkullType();
/**
@ -91,5 +99,6 @@ public interface Skull extends BlockState {
* @deprecated check {@link Material} instead
*/
@Deprecated
@Contract("_ -> fail")
public void setSkullType(SkullType skullType);
}

29
paper-api/src/main/java/org/bukkit/block/Structure.java
View File

@ -5,6 +5,7 @@ import org.bukkit.block.structure.StructureRotation;
import org.bukkit.block.structure.UsageMode;
import org.bukkit.entity.LivingEntity;
import org.bukkit.util.BlockVector;
import org.jetbrains.annotations.NotNull;
/**
* Represents a structure block that can save and load blocks from a file. They
@ -17,6 +18,7 @@ public interface Structure extends BlockState {
*
* @return structure name
*/
@NotNull
String getStructureName();
/**
@ -27,21 +29,22 @@ public interface Structure extends BlockState {
*
* @param name the case-sensitive name of this structure
*/
void setStructureName(String name);
void setStructureName(@NotNull String name);
/**
* Get the name of who created this structure.
*
* @return the name of whoever created this structure.
*/
@NotNull
String getAuthor();
/**
* Set the name of whoever created this structure.
*
* @param author whoever created this structure
* @param author whoever created this structure (not empty)
*/
void setAuthor(String author);
void setAuthor(@NotNull String author);
/**
* Set the name of whoever created this structure using a
@ -49,7 +52,7 @@ public interface Structure extends BlockState {
*
* @param livingEntity the entity who created this structure
*/
void setAuthor(LivingEntity livingEntity);
void setAuthor(@NotNull LivingEntity livingEntity);
/**
* The relative position of the structure outline based on the position of
@ -59,6 +62,7 @@ public interface Structure extends BlockState {
* @return a Location which contains the relative distance this structure is
* from the structure block.
*/
@NotNull
BlockVector getRelativePosition();
/**
@ -68,7 +72,7 @@ public interface Structure extends BlockState {
* @param vector the {@link BlockVector} containing the relative origin
* coordinates of this structure.
*/
void setRelativePosition(BlockVector vector);
void setRelativePosition(@NotNull BlockVector vector);
/**
* The distance to the opposite corner of this structure. The maximum
@ -79,6 +83,7 @@ public interface Structure extends BlockState {
* @return a {@link BlockVector} which contains the total size of the
* structure.
*/
@NotNull
BlockVector getStructureSize();
/**
@ -88,20 +93,21 @@ public interface Structure extends BlockState {
* @param vector the {@link BlockVector} containing the size of this
* structure, based off of the origin coordinates.
*/
void setStructureSize(BlockVector vector);
void setStructureSize(@NotNull BlockVector vector);
/**
* Sets the mirroring of the structure.
*
* @param mirror the new mirroring method
*/
void setMirror(Mirror mirror);
void setMirror(@NotNull Mirror mirror);
/**
* How this structure is mirrored.
*
* @return the current mirroring method
*/
@NotNull
Mirror getMirror();
/**
@ -109,13 +115,14 @@ public interface Structure extends BlockState {
*
* @param rotation the new rotation
*/
void setRotation(StructureRotation rotation);
void setRotation(@NotNull StructureRotation rotation);
/**
* Get how this structure is rotated.
*
* @return the new rotation
*/
@NotNull
StructureRotation getRotation();
/**
@ -123,13 +130,14 @@ public interface Structure extends BlockState {
*
* @param mode the new mode to set.
*/
void setUsageMode(UsageMode mode);
void setUsageMode(@NotNull UsageMode mode);
/**
* Get the {@link UsageMode} of this structure block.
*
* @return the mode this block is currently in.
*/
@NotNull
UsageMode getUsageMode();
/**
@ -220,7 +228,7 @@ public interface Structure extends BlockState {
*
* @param metadata the function to perform on the selected location
*/
void setMetadata(String metadata);
void setMetadata(@NotNull String metadata);
/**
* Get the metadata function this structure block will perform when
@ -230,5 +238,6 @@ public interface Structure extends BlockState {
*
* @return the function that will be performed when this block is activated
*/
@NotNull
String getMetadata();
}

10
paper-api/src/main/java/org/bukkit/block/banner/Pattern.java
View File

@ -6,6 +6,7 @@ import java.util.NoSuchElementException;
import org.bukkit.DyeColor;
import org.bukkit.configuration.serialization.ConfigurationSerializable;
import org.bukkit.configuration.serialization.SerializableAs;
import org.jetbrains.annotations.NotNull;
@SerializableAs("Pattern")
public class Pattern implements ConfigurationSerializable {
@ -23,7 +24,7 @@ public class Pattern implements ConfigurationSerializable {
* @param color the pattern color
* @param pattern the pattern type
*/
public Pattern(DyeColor color, PatternType pattern) {
public Pattern(@NotNull DyeColor color, @NotNull PatternType pattern) {
this.color = color;
this.pattern = pattern;
}
@ -33,12 +34,12 @@ public class Pattern implements ConfigurationSerializable {
*
* @param map the map to deserialize from
*/
public Pattern(Map<String, Object> map) {
public Pattern(@NotNull Map<String, Object> map) {
color = DyeColor.legacyValueOf(getString(map, COLOR));
pattern = PatternType.getByIdentifier(getString(map, PATTERN));
}
private static String getString(Map<?, ?> map, Object key) {
private static String getString(@NotNull Map<?, ?> map, @NotNull Object key) {
Object str = map.get(key);
if (str instanceof String) {
return (String) str;
@ -46,6 +47,7 @@ public class Pattern implements ConfigurationSerializable {
throw new NoSuchElementException(map + " does not contain " + key);
}
@NotNull
@Override
public Map<String, Object> serialize() {
return ImmutableMap.<String, Object>of(
@ -59,6 +61,7 @@ public class Pattern implements ConfigurationSerializable {
*
* @return the color of the pattern
*/
@NotNull
public DyeColor getColor() {
return color;
}
@ -68,6 +71,7 @@ public class Pattern implements ConfigurationSerializable {
*
* @return the pattern type
*/
@NotNull
public PatternType getPattern() {
return pattern;
}

11
paper-api/src/main/java/org/bukkit/block/banner/PatternType.java
View File

@ -1,5 +1,9 @@
package org.bukkit.block.banner;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.HashMap;
import java.util.Map;
@ -53,7 +57,7 @@ public enum PatternType {
}
}
private PatternType(String key) {
private PatternType(@NotNull String key) {
this.identifier = key;
}
@ -63,6 +67,7 @@ public enum PatternType {
*
* @return the pattern's identifier
*/
@NotNull
public String getIdentifier() {
return identifier;
}
@ -74,7 +79,9 @@ public enum PatternType {
* @param identifier the identifier
* @return the matched pattern type or null
*/
public static PatternType getByIdentifier(String identifier) {
@Contract("null -> null")
@Nullable
public static PatternType getByIdentifier(@Nullable String identifier) {
return byString.get(identifier);
}
}

5
paper-api/src/main/java/org/bukkit/block/data/Bisected.java
View File

@ -1,5 +1,7 @@
package org.bukkit.block.data;
import org.jetbrains.annotations.NotNull;
/**
* 'half' denotes which half of a two block tall material this block is.
* <br>
@ -12,6 +14,7 @@ public interface Bisected extends BlockData {
*
* @return the 'half' value
*/
@NotNull
Half getHalf();
/**
@ -19,7 +22,7 @@ public interface Bisected extends BlockData {
*
* @param half the new 'half' value
*/
void setHalf(Half half);
void setHalf(@NotNull Half half);
/**
* The half of a vertically bisected block.

11
paper-api/src/main/java/org/bukkit/block/data/BlockData.java
View File

@ -2,6 +2,8 @@ package org.bukkit.block.data;
import org.bukkit.Material;
import org.bukkit.Server;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
public interface BlockData extends Cloneable {
@ -10,6 +12,7 @@ public interface BlockData extends Cloneable {
*
* @return the material
*/
@NotNull
Material getMaterial();
/**
@ -19,6 +22,7 @@ public interface BlockData extends Cloneable {
*
* @return serialized data string for this block
*/
@NotNull
String getAsString();
/**
@ -47,6 +51,7 @@ public interface BlockData extends Cloneable {
*
* @return serialized data string for this block
*/
@NotNull
String getAsString(boolean hideUnspecified);
/**
@ -61,7 +66,8 @@ public interface BlockData extends Cloneable {
* @param data the data to merge from
* @return a new instance of this blockdata with the merged data
*/
BlockData merge(BlockData data);
@NotNull
BlockData merge(@NotNull BlockData data);
/**
* Checks if the specified BlockData matches this block data.
@ -78,12 +84,13 @@ public interface BlockData extends Cloneable {
* @param data the data to match against (normally a parsed constant)
* @return if there is a match
*/
boolean matches(BlockData data);
boolean matches(@Nullable BlockData data);
/**
* Returns a copy of this BlockData.
*
* @return a copy of the block data
*/
@NotNull
BlockData clone();
}

5
paper-api/src/main/java/org/bukkit/block/data/Directional.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block.data;
import java.util.Set;
import org.bukkit.block.BlockFace;
import org.jetbrains.annotations.NotNull;
/**
* 'facing' represents the face towards which the block is pointing.
@ -16,6 +17,7 @@ public interface Directional extends BlockData {
*
* @return the 'facing' value
*/
@NotNull
BlockFace getFacing();
/**
@ -23,12 +25,13 @@ public interface Directional extends BlockData {
*
* @param facing the new 'facing' value
*/
void setFacing(BlockFace facing);
void setFacing(@NotNull BlockFace facing);
/**
* Gets the faces which are applicable to this block.
*
* @return the allowed 'facing' values
*/
@NotNull
Set<BlockFace> getFaces();
}

8
paper-api/src/main/java/org/bukkit/block/data/MultipleFacing.java
View File

@ -2,6 +2,8 @@ package org.bukkit.block.data;
import java.util.Set;
import org.bukkit.block.BlockFace;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* This class encompasses the 'north', 'east', 'south', 'west', 'up', 'down'
@ -19,7 +21,7 @@ public interface MultipleFacing extends BlockData {
* @param face to check
* @return if face is enabled
*/
boolean hasFace(BlockFace face);
boolean hasFace(@NotNull BlockFace face);
/**
* Set whether this block has the specified face enabled.
@ -27,13 +29,14 @@ public interface MultipleFacing extends BlockData {
* @param face to set
* @param has the face
*/
void setFace(BlockFace face, boolean has);
void setFace(@Nullable BlockFace face, boolean has);
/**
* Get all of the faces which are enabled on this block.
*
* @return all faces enabled
*/
@NotNull
Set<BlockFace> getFaces();
/**
@ -41,5 +44,6 @@ public interface MultipleFacing extends BlockData {
*
* @return all allowed faces
*/
@NotNull
Set<BlockFace> getAllowedFaces();
}

5
paper-api/src/main/java/org/bukkit/block/data/Orientable.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block.data;
import java.util.Set;
import org.bukkit.Axis;
import org.jetbrains.annotations.NotNull;
/**
* 'axis' represents the axis along whilst this block is oriented.
@ -17,6 +18,7 @@ public interface Orientable extends BlockData {
*
* @return the 'axis' value
*/
@NotNull
Axis getAxis();
/**
@ -24,12 +26,13 @@ public interface Orientable extends BlockData {
*
* @param axis the new 'axis' value
*/
void setAxis(Axis axis);
void setAxis(@NotNull Axis axis);
/**
* Gets the axes which are applicable to this block.
*
* @return the allowed 'axis' values
*/
@NotNull
Set<Axis> getAxes();
}

6
paper-api/src/main/java/org/bukkit/block/data/Rail.java
View File

@ -1,5 +1,7 @@
package org.bukkit.block.data;
import org.jetbrains.annotations.NotNull;
import java.util.Set;
/**
@ -15,6 +17,7 @@ public interface Rail extends BlockData {
*
* @return the 'shape' value
*/
@NotNull
Shape getShape();
/**
@ -22,13 +25,14 @@ public interface Rail extends BlockData {
*
* @param shape the new 'shape' value
*/
void setShape(Shape shape);
void setShape(@NotNull Shape shape);
/**
* Gets the shapes which are applicable to this block.
*
* @return the allowed 'shape' values
*/
@NotNull
Set<Shape> getShapes();
/**

4
paper-api/src/main/java/org/bukkit/block/data/Rotatable.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block.data;
import org.bukkit.block.BlockFace;
import org.jetbrains.annotations.NotNull;
/**
* 'rotation' represents the current rotation of this block.
@ -12,6 +13,7 @@ public interface Rotatable extends BlockData {
*
* @return the 'rotation' value
*/
@NotNull
BlockFace getRotation();
/**
@ -19,5 +21,5 @@ public interface Rotatable extends BlockData {
*
* @param rotation the new 'rotation' value
*/
void setRotation(BlockFace rotation);
void setRotation(@NotNull BlockFace rotation);
}

4
paper-api/src/main/java/org/bukkit/block/data/type/Bed.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block.data.type;
import org.bukkit.block.data.Bisected;
import org.bukkit.block.data.Directional;
import org.jetbrains.annotations.NotNull;
/**
* Similar to {@link Bisected}, 'part' denotes which half of the bed this block
@ -17,6 +18,7 @@ public interface Bed extends Directional {
*
* @return the 'part' value
*/
@NotNull
Part getPart();
/**
@ -24,7 +26,7 @@ public interface Bed extends Directional {
*
* @param part the new 'part' value
*/
void setPart(Part part);
void setPart(@NotNull Part part);
/**
* Gets the value of the 'occupied' property.

2
paper-api/src/main/java/org/bukkit/block/data/type/BrewingStand.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block.data.type;
import java.util.Set;
import org.bukkit.block.data.BlockData;
import org.jetbrains.annotations.NotNull;
/**
* Interface to the 'has_bottle_0', 'has_bottle_1', 'has_bottle_2' flags on a
@ -32,6 +33,7 @@ public interface BrewingStand extends BlockData {
*
* @return set of all bottles
*/
@NotNull
Set<Integer> getBottles();
/**

4
paper-api/src/main/java/org/bukkit/block/data/type/Chest.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block.data.type;
import org.bukkit.block.data.Directional;
import org.bukkit.block.data.Waterlogged;
import org.jetbrains.annotations.NotNull;
/**
* 'type' represents which part of a double chest this block is, or if it is a
@ -14,6 +15,7 @@ public interface Chest extends Directional, Waterlogged {
*
* @return the 'type' value
*/
@NotNull
Type getType();
/**
@ -21,7 +23,7 @@ public interface Chest extends Directional, Waterlogged {
*
* @param type the new 'type' value
*/
void setType(Type type);
void setType(@NotNull Type type);
/**
* Type of this chest block.

4
paper-api/src/main/java/org/bukkit/block/data/type/Comparator.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block.data.type;
import org.bukkit.block.data.Directional;
import org.bukkit.block.data.Powerable;
import org.jetbrains.annotations.NotNull;
/**
* 'mode' indicates what mode this comparator will operate in.
@ -13,6 +14,7 @@ public interface Comparator extends Directional, Powerable {
*
* @return the 'mode' value
*/
@NotNull
Mode getMode();
/**
@ -20,7 +22,7 @@ public interface Comparator extends Directional, Powerable {
*
* @param mode the new 'mode' value
*/
void setMode(Mode mode);
void setMode(@NotNull Mode mode);
/**
* The mode in which a comparator will operate in.

4
paper-api/src/main/java/org/bukkit/block/data/type/Door.java
View File

@ -4,6 +4,7 @@ import org.bukkit.block.data.Bisected;
import org.bukkit.block.data.Directional;
import org.bukkit.block.data.Openable;
import org.bukkit.block.data.Powerable;
import org.jetbrains.annotations.NotNull;
/**
* 'hinge' indicates which hinge this door is attached to and will rotate around
@ -16,6 +17,7 @@ public interface Door extends Bisected, Directional, Openable, Powerable {
*
* @return the 'hinge' value
*/
@NotNull
Hinge getHinge();
/**
@ -23,7 +25,7 @@ public interface Door extends Bisected, Directional, Openable, Powerable {
*
* @param hinge the new 'hinge' value
*/
void setHinge(Hinge hinge);
void setHinge(@NotNull Hinge hinge);
/**
* The hinge of a door.

7
paper-api/src/main/java/org/bukkit/block/data/type/NoteBlock.java
View File

@ -3,6 +3,7 @@ package org.bukkit.block.data.type;
import org.bukkit.Instrument;
import org.bukkit.Note;
import org.bukkit.block.data.Powerable;
import org.jetbrains.annotations.NotNull;
/**
* 'instrument' is the type of sound made when this note block is activated.
@ -16,6 +17,7 @@ public interface NoteBlock extends Powerable {
*
* @return the 'instrument' value
*/
@NotNull
Instrument getInstrument();
/**
@ -23,13 +25,14 @@ public interface NoteBlock extends Powerable {
*
* @param instrument the new 'instrument' value
*/
void setInstrument(Instrument instrument);
void setInstrument(@NotNull Instrument instrument);
/**
* Gets the value of the 'note' property.
*
* @return the 'note' value
*/
@NotNull
Note getNote();
/**
@ -37,5 +40,5 @@ public interface NoteBlock extends Powerable {
*
* @param note the new 'note' value
*/
void setNote(Note note);
void setNote(@NotNull Note note);
}

7
paper-api/src/main/java/org/bukkit/block/data/type/RedstoneWire.java
View File

@ -3,6 +3,7 @@ package org.bukkit.block.data.type;
import java.util.Set;
import org.bukkit.block.BlockFace;
import org.bukkit.block.data.AnaloguePowerable;
import org.jetbrains.annotations.NotNull;
/**
* 'north', 'east', 'south', 'west' represent the types of connections this
@ -16,7 +17,8 @@ public interface RedstoneWire extends AnaloguePowerable {
* @param face to check
* @return connection type
*/
Connection getFace(BlockFace face);
@NotNull
Connection getFace(@NotNull BlockFace face);
/**
* Sets the type of connection on the specified face.
@ -24,13 +26,14 @@ public interface RedstoneWire extends AnaloguePowerable {
* @param face to set
* @param connection the connection type
*/
void setFace(BlockFace face, Connection connection);
void setFace(@NotNull BlockFace face, @NotNull Connection connection);
/**
* Gets all of this faces which may be set on this block.
*
* @return all allowed faces
*/
@NotNull
Set<BlockFace> getAllowedFaces();
/**

4
paper-api/src/main/java/org/bukkit/block/data/type/Slab.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block.data.type;
import org.bukkit.block.data.Waterlogged;
import org.jetbrains.annotations.NotNull;
/**
* 'type' represents what state the slab is in - either top, bottom, or a double
@ -13,6 +14,7 @@ public interface Slab extends Waterlogged {
*
* @return the 'type' value
*/
@NotNull
Type getType();
/**
@ -20,7 +22,7 @@ public interface Slab extends Waterlogged {
*
* @param type the new 'type' value
*/
void setType(Type type);
void setType(@NotNull Type type);
/**
* The type of the slab.

4
paper-api/src/main/java/org/bukkit/block/data/type/Stairs.java
View File

@ -3,6 +3,7 @@ package org.bukkit.block.data.type;
import org.bukkit.block.data.Bisected;
import org.bukkit.block.data.Directional;
import org.bukkit.block.data.Waterlogged;
import org.jetbrains.annotations.NotNull;
/**
* 'shape' represents the texture and bounding box shape of these stairs.
@ -14,6 +15,7 @@ public interface Stairs extends Bisected, Directional, Waterlogged {
*
* @return the 'shape' value
*/
@NotNull
Shape getShape();
/**
@ -21,7 +23,7 @@ public interface Stairs extends Bisected, Directional, Waterlogged {
*
* @param shape the new 'shape' value
*/
void setShape(Shape shape);
void setShape(@NotNull Shape shape);
/**
* The shape of a stair block - used for constructing corners.

4
paper-api/src/main/java/org/bukkit/block/data/type/StructureBlock.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block.data.type;
import org.bukkit.block.data.BlockData;
import org.jetbrains.annotations.NotNull;
/**
* 'mode' represents the different modes in which this structure block may
@ -13,6 +14,7 @@ public interface StructureBlock extends BlockData {
*
* @return the 'mode' value
*/
@NotNull
Mode getMode();
/**
@ -20,7 +22,7 @@ public interface StructureBlock extends BlockData {
*
* @param mode the new 'mode' value
*/
void setMode(Mode mode);
void setMode(@NotNull Mode mode);
/**
* Operating mode of a structure block.

4
paper-api/src/main/java/org/bukkit/block/data/type/Switch.java
View File

@ -2,6 +2,7 @@ package org.bukkit.block.data.type;
import org.bukkit.block.data.Directional;
import org.bukkit.block.data.Powerable;
import org.jetbrains.annotations.NotNull;
/**
* 'face' represents the face to which a lever or button is stuck.
@ -16,6 +17,7 @@ public interface Switch extends Directional, Powerable {
*
* @return the 'face' value
*/
@NotNull
Face getFace();
/**
@ -23,7 +25,7 @@ public interface Switch extends Directional, Powerable {
*
* @param face the new 'face' value
*/
void setFace(Face face);
void setFace(@NotNull Face face);
/**
* The face to which a switch type block is stuck.

4
paper-api/src/main/java/org/bukkit/block/data/type/TechnicalPiston.java
View File

@ -1,6 +1,7 @@
package org.bukkit.block.data.type;
import org.bukkit.block.data.Directional;
import org.jetbrains.annotations.NotNull;
/**
* 'type' represents the type of piston which this (technical) block corresponds
@ -13,6 +14,7 @@ public interface TechnicalPiston extends Directional {
*
* @return the 'type' value
*/
@NotNull
Type getType();
/**
@ -20,7 +22,7 @@ public interface TechnicalPiston extends Directional {
*
* @param type the new 'type' value
*/
void setType(Type type);
void setType(@NotNull Type type);
/**
* Different piston variants.

23
paper-api/src/main/java/org/bukkit/boss/BossBar.java
View File

@ -1,6 +1,9 @@
package org.bukkit.boss;
import org.bukkit.entity.Player;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.List;
@ -11,6 +14,7 @@ public interface BossBar {
*
* @return the title of the bar
*/
@NotNull
String getTitle();
/**
@ -18,13 +22,14 @@ public interface BossBar {
*
* @param title the title of the bar
*/
void setTitle(String title);
void setTitle(@Nullable String title);
/**
* Returns the color of this boss bar
*
* @return the color of the bar
*/
@NotNull
BarColor getColor();
/**
@ -32,13 +37,14 @@ public interface BossBar {
*
* @param color the color of the bar
*/
void setColor(BarColor color);
void setColor(@NotNull BarColor color);
/**
* Returns the style of this boss bar
*
* @return the style of the bar
*/
@NotNull
BarStyle getStyle();
/**
@ -46,21 +52,21 @@ public interface BossBar {
*
* @param style the style of the bar
*/
void setStyle(BarStyle style);
void setStyle(@NotNull BarStyle style);
/**
* Remove an existing flag on this boss bar
*
* @param flag the existing flag to remove
*/
void removeFlag(BarFlag flag);
void removeFlag(@NotNull BarFlag flag);
/**
* Add an optional flag to this boss bar
*
* @param flag an optional flag to set on the boss bar
*/
void addFlag(BarFlag flag);
void addFlag(@NotNull BarFlag flag);
/**
* Returns whether this boss bar as the passed flag set
@ -68,7 +74,7 @@ public interface BossBar {
* @param flag the flag to check
* @return whether it has the flag
*/
boolean hasFlag(BarFlag flag);
boolean hasFlag(@NotNull BarFlag flag);
/**
* Sets the progress of the bar. Values should be between 0.0 (empty) and
@ -90,7 +96,7 @@ public interface BossBar {
*
* @param player the player to add
*/
void addPlayer(Player player);
void addPlayer(@NotNull Player player);
/**
* Removes the player from this boss bar causing it to be removed from their
@ -98,7 +104,7 @@ public interface BossBar {
*
* @param player the player to remove
*/
void removePlayer(Player player);
void removePlayer(@NotNull Player player);
/**
* Removes all players from this boss bar
@ -112,6 +118,7 @@ public interface BossBar {
*
* @return a immutable list of players
*/
@NotNull
List<Player> getPlayers();
/**

2
paper-api/src/main/java/org/bukkit/command/BlockCommandSender.java
View File

@ -1,6 +1,7 @@
package org.bukkit.command;
import org.bukkit.block.Block;
import org.jetbrains.annotations.NotNull;
public interface BlockCommandSender extends CommandSender {
@ -9,5 +10,6 @@ public interface BlockCommandSender extends CommandSender {
*
* @return Block for the command sender
*/
@NotNull
public Block getBlock();
}

73
paper-api/src/main/java/org/bukkit/command/Command.java
View File

@ -18,6 +18,8 @@ import org.bukkit.plugin.PluginDescriptionFile;
import org.bukkit.util.StringUtil;
import com.google.common.collect.ImmutableList;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents a Command, which executes various tasks upon user input
@ -28,22 +30,22 @@ public abstract class Command {
private String label;
private List<String> aliases;
private List<String> activeAliases;
private CommandMap commandMap = null;
protected String description = "";
private CommandMap commandMap;
protected String description;
protected String usageMessage;
private String permission;
private String permissionMessage;
protected Command(String name) {
protected Command(@NotNull String name) {
this(name, "", "/" + name, new ArrayList<String>());
}
protected Command(String name, String description, String usageMessage, List<String> aliases) {
protected Command(@NotNull String name, @NotNull String description, @NotNull String usageMessage, @NotNull List<String> aliases) {
this.name = name;
this.nextLabel = name;
this.label = name;
this.description = description;
this.usageMessage = usageMessage;
this.description = (description == null) ? "" : description;
this.usageMessage = (usageMessage == null) ? "/" + name : usageMessage;
this.aliases = aliases;
this.activeAliases = new ArrayList<String>(aliases);
}
@ -56,7 +58,7 @@ public abstract class Command {
* @param args All arguments passed to the command, split via ' '
* @return true if the command was successful, otherwise false
*/
public abstract boolean execute(CommandSender sender, String commandLabel, String[] args);
public abstract boolean execute(@NotNull CommandSender sender, @NotNull String commandLabel, @NotNull String[] args);
/**
* Executed on tab completion for this command, returning a list of
@ -69,7 +71,8 @@ public abstract class Command {
* will never be null. List may be immutable.
* @throws IllegalArgumentException if sender, alias, or args is null
*/
public List<String> tabComplete(CommandSender sender, String alias, String[] args) throws IllegalArgumentException {
@NotNull
public List<String> tabComplete(@NotNull CommandSender sender, @NotNull String alias, @NotNull String[] args) throws IllegalArgumentException {
return tabComplete0(sender, alias, args, null);
}
@ -85,11 +88,13 @@ public abstract class Command {
* will never be null. List may be immutable.
* @throws IllegalArgumentException if sender, alias, or args is null
*/
public List<String> tabComplete(CommandSender sender, String alias, String[] args, Location location) throws IllegalArgumentException {
@NotNull
public List<String> tabComplete(@NotNull CommandSender sender, @NotNull String alias, @NotNull String[] args, @Nullable Location location) throws IllegalArgumentException {
return tabComplete(sender, alias, args);
}
private List<String> tabComplete0(CommandSender sender, String alias, String[] args, Location location) throws IllegalArgumentException {
@NotNull
private List<String> tabComplete0(@NotNull CommandSender sender, @NotNull String alias, @NotNull String[] args, @Nullable Location location) throws IllegalArgumentException {
Validate.notNull(sender, "Sender cannot be null");
Validate.notNull(args, "Arguments cannot be null");
Validate.notNull(alias, "Alias cannot be null");
@ -119,6 +124,7 @@ public abstract class Command {
*
* @return Name of this command
*/
@NotNull
public String getName() {
return name;
}
@ -134,9 +140,9 @@ public abstract class Command {
* @return returns true if the name change happened instantly or false if
* the command was already registered
*/
public boolean setName(String name) {
public boolean setName(@NotNull String name) {
if (!isRegistered()) {
this.name = name;
this.name = (name == null) ? "" : name;
return true;
}
return false;
@ -148,6 +154,7 @@ public abstract class Command {
*
* @return Permission name, or null if none
*/
@Nullable
public String getPermission() {
return permission;
}
@ -158,7 +165,7 @@ public abstract class Command {
*
* @param permission Permission name or null
*/
public void setPermission(String permission) {
public void setPermission(@Nullable String permission) {
this.permission = permission;
}
@ -172,7 +179,7 @@ public abstract class Command {
* @param target User to test
* @return true if they can use it, otherwise false
*/
public boolean testPermission(CommandSender target) {
public boolean testPermission(@NotNull CommandSender target) {
if (testPermissionSilent(target)) {
return true;
}
@ -197,7 +204,7 @@ public abstract class Command {
* @param target User to test
* @return true if they can use it, otherwise false
*/
public boolean testPermissionSilent(CommandSender target) {
public boolean testPermissionSilent(@NotNull CommandSender target) {
if ((permission == null) || (permission.length() == 0)) {
return true;
}
@ -216,6 +223,7 @@ public abstract class Command {
*
* @return Label of this command
*/
@NotNull
public String getLabel() {
return label;
}
@ -231,7 +239,10 @@ public abstract class Command {
* @return returns true if the name change happened instantly or false if
* the command was already registered
*/
public boolean setLabel(String name) {
public boolean setLabel(@NotNull String name) {
if (name == null) {
name = "";
}
this.nextLabel = name;
if (!isRegistered()) {
this.label = name;
@ -248,7 +259,7 @@ public abstract class Command {
* @return true if the registration was successful (the current registered
* CommandMap was the passed CommandMap or null) false otherwise
*/
public boolean register(CommandMap commandMap) {
public boolean register(@NotNull CommandMap commandMap) {
if (allowChangesFrom(commandMap)) {
this.commandMap = commandMap;
return true;
@ -266,7 +277,7 @@ public abstract class Command {
* registered CommandMap was the passed CommandMap or null) false
* otherwise
*/
public boolean unregister(CommandMap commandMap) {
public boolean unregister(@NotNull CommandMap commandMap) {
if (allowChangesFrom(commandMap)) {
this.commandMap = null;
this.activeAliases = new ArrayList<String>(this.aliases);
@ -277,7 +288,7 @@ public abstract class Command {
return false;
}
private boolean allowChangesFrom(CommandMap commandMap) {
private boolean allowChangesFrom(@NotNull CommandMap commandMap) {
return (null == this.commandMap || this.commandMap == commandMap);
}
@ -295,6 +306,7 @@ public abstract class Command {
*
* @return List of aliases
*/
@NotNull
public List<String> getAliases() {
return activeAliases;
}
@ -305,6 +317,7 @@ public abstract class Command {
*
* @return Permission check failed message
*/
@Nullable
public String getPermissionMessage() {
return permissionMessage;
}
@ -314,6 +327,7 @@ public abstract class Command {
*
* @return Description of this command
*/
@NotNull
public String getDescription() {
return description;
}
@ -323,6 +337,7 @@ public abstract class Command {
*
* @return One or more example usages
*/
@NotNull
public String getUsage() {
return usageMessage;
}
@ -336,7 +351,8 @@ public abstract class Command {
* @param aliases aliases to register to this command
* @return this command object, for chaining
*/
public Command setAliases(List<String> aliases) {
@NotNull
public Command setAliases(@NotNull List<String> aliases) {
this.aliases = aliases;
if (!isRegistered()) {
this.activeAliases = new ArrayList<String>(aliases);
@ -352,8 +368,9 @@ public abstract class Command {
* @param description new command description
* @return this command object, for chaining
*/
public Command setDescription(String description) {
this.description = description;
@NotNull
public Command setDescription(@NotNull String description) {
this.description = description == null ? "" : "";
return this;
}
@ -364,7 +381,8 @@ public abstract class Command {
* default message, or an empty string to indicate no message
* @return this command object, for chaining
*/
public Command setPermissionMessage(String permissionMessage) {
@NotNull
public Command setPermissionMessage(@Nullable String permissionMessage) {
this.permissionMessage = permissionMessage;
return this;
}
@ -375,16 +393,17 @@ public abstract class Command {
* @param usage new example usage
* @return this command object, for chaining
*/
public Command setUsage(String usage) {
this.usageMessage = usage;
@NotNull
public Command setUsage(@NotNull String usage) {
this.usageMessage = (usage == null) ? "" : usage;
return this;
}
public static void broadcastCommandMessage(CommandSender source, String message) {
public static void broadcastCommandMessage(@NotNull CommandSender source, @NotNull String message) {
broadcastCommandMessage(source, message, true);
}
public static void broadcastCommandMessage(CommandSender source, String message, boolean sendToSource) {
public static void broadcastCommandMessage(@NotNull CommandSender source, @NotNull String message, boolean sendToSource) {
String result = source.getName() + ": " + message;
if (source instanceof BlockCommandSender) {

4
paper-api/src/main/java/org/bukkit/command/CommandExecutor.java
View File

@ -1,5 +1,7 @@
package org.bukkit.command;
import org.jetbrains.annotations.NotNull;
/**
* Represents a class which contains a single method for executing commands
*/
@ -17,5 +19,5 @@ public interface CommandExecutor {
* @param args Passed command arguments
* @return true if a valid command, otherwise false
*/
public boolean onCommand(CommandSender sender, Command command, String label, String[] args);
public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command, @NotNull String label, @NotNull String[] args);
}

19
paper-api/src/main/java/org/bukkit/command/CommandMap.java
View File

@ -2,6 +2,8 @@ package org.bukkit.command;
import java.util.List;
import org.bukkit.Location;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
public interface CommandMap {
@ -20,7 +22,7 @@ public interface CommandMap {
* a ':' one or more times to make the command unique
* @param commands a list of commands to register
*/
public void registerAll(String fallbackPrefix, List<Command> commands);
public void registerAll(@NotNull String fallbackPrefix, @NotNull List<Command> commands);
/**
* Registers a command. Returns true on success; false if name is already
@ -42,7 +44,7 @@ public interface CommandMap {
* otherwise, which indicates the fallbackPrefix was used one or more
* times
*/
public boolean register(String label, String fallbackPrefix, Command command);
public boolean register(@NotNull String label, @NotNull String fallbackPrefix, @NotNull Command command);
/**
* Registers a command. Returns true on success; false if name is already
@ -64,7 +66,7 @@ public interface CommandMap {
* otherwise, which indicates the fallbackPrefix was used one or more
* times
*/
public boolean register(String fallbackPrefix, Command command);
public boolean register(@NotNull String fallbackPrefix, @NotNull Command command);
/**
* Looks for the requested command and executes it if found.
@ -75,7 +77,7 @@ public interface CommandMap {
* @throws CommandException Thrown when the executor for the given command
* fails with an unhandled exception
*/
public boolean dispatch(CommandSender sender, String cmdLine) throws CommandException;
public boolean dispatch(@NotNull CommandSender sender, @NotNull String cmdLine) throws CommandException;
/**
* Clears all registered commands.
@ -89,7 +91,8 @@ public interface CommandMap {
* @return Command with the specified name or null if a command with that
* label doesn't exist
*/
public Command getCommand(String name);
@Nullable
public Command getCommand(@NotNull String name);
/**
* Looks for the requested command and executes an appropriate
@ -105,7 +108,8 @@ public interface CommandMap {
* command fails with an unhandled exception
* @throws IllegalArgumentException if either sender or cmdLine are null
*/
public List<String> tabComplete(CommandSender sender, String cmdLine) throws IllegalArgumentException;
@Nullable
public List<String> tabComplete(@NotNull CommandSender sender, @NotNull String cmdLine) throws IllegalArgumentException;
/**
* Looks for the requested command and executes an appropriate
@ -122,5 +126,6 @@ public interface CommandMap {
* command fails with an unhandled exception
* @throws IllegalArgumentException if either sender or cmdLine are null
*/
public List<String> tabComplete(CommandSender sender, String cmdLine, Location location) throws IllegalArgumentException;
@Nullable
public List<String> tabComplete(@NotNull CommandSender sender, @NotNull String cmdLine, @Nullable Location location) throws IllegalArgumentException;
}

7
paper-api/src/main/java/org/bukkit/command/CommandSender.java
View File

@ -2,6 +2,7 @@ package org.bukkit.command;
import org.bukkit.Server;
import org.bukkit.permissions.Permissible;
import org.jetbrains.annotations.NotNull;
public interface CommandSender extends Permissible {
@ -10,20 +11,21 @@ public interface CommandSender extends Permissible {
*
* @param message Message to be displayed
*/
public void sendMessage(String message);
public void sendMessage(@NotNull String message);
/**
* Sends this sender multiple messages
*
* @param messages An array of messages to be displayed
*/
public void sendMessage(String[] messages);
public void sendMessage(@NotNull String[] messages);
/**
* Returns the server instance that this command is running on
*
* @return Server instance
*/
@NotNull
public Server getServer();
/**
@ -31,5 +33,6 @@ public interface CommandSender extends Permissible {
*
* @return Name of the sender
*/
@NotNull
public String getName();
}

7
paper-api/src/main/java/org/bukkit/command/FormattedCommandAlias.java
View File

@ -3,17 +3,18 @@ package org.bukkit.command;
import java.util.ArrayList;
import org.bukkit.Bukkit;
import org.jetbrains.annotations.NotNull;
public class FormattedCommandAlias extends Command {
private final String[] formatStrings;
public FormattedCommandAlias(String alias, String[] formatStrings) {
public FormattedCommandAlias(@NotNull String alias, @NotNull String[] formatStrings) {
super(alias);
this.formatStrings = formatStrings;
}
@Override
public boolean execute(CommandSender sender, String commandLabel, String[] args) {
public boolean execute(@NotNull CommandSender sender, @NotNull String commandLabel, @NotNull String[] args) {
boolean result = false;
ArrayList<String> commands = new ArrayList<String>();
for (String formatString : formatStrings) {
@ -36,7 +37,7 @@ public class FormattedCommandAlias extends Command {
return result;
}
private String buildCommand(String formatString, String[] args) {
private String buildCommand(@NotNull String formatString, @NotNull String[] args) {
int index = formatString.indexOf('$');
while (index != -1) {
int start = index;

Some files were not shown because too many files have changed in this diff Show More