SPIGOT-2540: Add nullability annotations to entire Bukkit API

By: Darkyenus <darkyenus@gmail.com>

paper-api/README.md

@@ -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

paper-api/pom.xml

@@ -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>

paper-api/src/main/java/org/bukkit/Achievement.java

@@ -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;
     }

paper-api/src/main/java/org/bukkit/Art.java

@@ -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));

paper-api/src/main/java/org/bukkit/BanEntry.java

@@ -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.

paper-api/src/main/java/org/bukkit/BanList.java

@@ -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);
 }

paper-api/src/main/java/org/bukkit/BlockChangeDelegate.java

@@ -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);
 
     /**

paper-api/src/main/java/org/bukkit/Bukkit.java

@@ -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();
     }

paper-api/src/main/java/org/bukkit/ChatColor.java

@@ -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();
 

paper-api/src/main/java/org/bukkit/Chunk.java

@@ -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();
 
     /**

paper-api/src/main/java/org/bukkit/ChunkSnapshot.java

@@ -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);
 
     /**

paper-api/src/main/java/org/bukkit/CoalType.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/Color.java

@@ -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);

paper-api/src/main/java/org/bukkit/CropState.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/Difficulty.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/DyeColor.java

@@ -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);
     }
 

paper-api/src/main/java/org/bukkit/Effect.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/EntityEffect.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/FireworkEffect.java

@@ -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(

paper-api/src/main/java/org/bukkit/GameMode.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/GameRule.java

@@ -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()]);
     }

paper-api/src/main/java/org/bukkit/GrassSpecies.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/Instrument.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/Keyed.java

@@ -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();
 }

paper-api/src/main/java/org/bukkit/Location.java

@@ -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");

paper-api/src/main/java/org/bukkit/Material.java

@@ -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;

paper-api/src/main/java/org/bukkit/Nameable.java

@@ -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);
 }

paper-api/src/main/java/org/bukkit/NamespacedKey.java

@@ -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);
     }
 }

paper-api/src/main/java/org/bukkit/Note.java

@@ -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());
     }

paper-api/src/main/java/org/bukkit/OfflinePlayer.java

@@ -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();
 
 }

paper-api/src/main/java/org/bukkit/Particle.java

@@ -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;
         }

paper-api/src/main/java/org/bukkit/Rotation.java

@@ -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];
     }

paper-api/src/main/java/org/bukkit/SandstoneType.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/Server.java

@@ -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();
 }

paper-api/src/main/java/org/bukkit/Statistic.java

@@ -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;
     }

paper-api/src/main/java/org/bukkit/StructureType.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/Tag.java

@@ -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();
 
 }

paper-api/src/main/java/org/bukkit/TravelAgent.java

@@ -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);
 }

paper-api/src/main/java/org/bukkit/TreeSpecies.java

@@ -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);
     }

paper-api/src/main/java/org/bukkit/UndefinedNullability.java

@@ -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 "";
+}

paper-api/src/main/java/org/bukkit/Warning.java

@@ -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;
             }

paper-api/src/main/java/org/bukkit/World.java

@@ -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);
         }

paper-api/src/main/java/org/bukkit/WorldBorder.java

@@ -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);
 }

paper-api/src/main/java/org/bukkit/WorldCreator.java

@@ -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) {

paper-api/src/main/java/org/bukkit/WorldType.java

@@ -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));
     }
 

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

@@ -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();
 }

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

@@ -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();
 }

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

@@ -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);
 }

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

@@ -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

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

@@ -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())));
         }

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

@@ -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

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

@@ -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);
 }

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

@@ -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();
 }

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

@@ -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:

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

@@ -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

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

@@ -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();
 }

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

@@ -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();
 }

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

@@ -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);
 }

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

@@ -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();
 }

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

@@ -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();
 
     /**

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

@@ -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();
 
     /**

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

@@ -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();
     }

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

@@ -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

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

@@ -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);
 }

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

@@ -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();
 }

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

@@ -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.

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

@@ -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);
 }

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

@@ -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);
     }

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

@@ -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();
 }

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

@@ -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.

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

@@ -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);
 }

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

@@ -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();
 }

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

@@ -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;
     }

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

@@ -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);
     }
 }

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

@@ -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.

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

@@ -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();
 }

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

@@ -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();
 }

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

@@ -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();
 }

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

@@ -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();
 }

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

@@ -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();
 
     /**

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

@@ -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);
 }

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

@@ -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.

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

@@ -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();
 
     /**

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

@@ -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.

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

@@ -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.

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

@@ -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.

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

@@ -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);
 }

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

@@ -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();
 
     /**

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

@@ -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.

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

@@ -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.

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

@@ -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.

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

@@ -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.

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

@@ -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.

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

@@ -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();
 
     /**

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

@@ -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();
 }

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

@@ -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;
+    private CommandMap commandMap;
-    protected String description = "";
+    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.description = (description == null) ? "" : description;
-        this.usageMessage = usageMessage;
+        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) {
+    @NotNull
-        this.description = description;
+    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) {
+    @NotNull
-        this.usageMessage = usage;
+    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) {

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

@@ -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);
 }

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

@@ -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;
 }

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

@@ -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();
 }

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

@@ -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;