SPIGOT-2540: Add nullability annotations to entire Bukkit API

By: Darkyenus <darkyenus@gmail.com>

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