SPIGOT-2540: Add nullability annotations to entire Bukkit API

By: Darkyenus <darkyenus@gmail.com>

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.