SPIGOT-2540: Add nullability annotations to entire Bukkit API

By: Darkyenus <darkyenus@gmail.com>

paper-api/src/main/java/org/bukkit/metadata/FixedMetadataValue.java

@@ -1,6 +1,8 @@
 package org.bukkit.metadata;
 
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * A FixedMetadataValue is a special case metadata item that contains the same
@@ -24,7 +26,7 @@ public class FixedMetadataValue extends LazyMetadataValue {
      * @param owningPlugin the {@link Plugin} that created this metadata value
      * @param value the value assigned to this metadata value
      */
-    public FixedMetadataValue(Plugin owningPlugin, final Object value) {
+    public FixedMetadataValue(@NotNull Plugin owningPlugin, @Nullable final Object value) {
         super(owningPlugin);
         this.internalValue = value;
     }
@@ -34,6 +36,7 @@ public class FixedMetadataValue extends LazyMetadataValue {
 
     }
 
+    @Nullable
     @Override
     public Object value() {
         return internalValue;

paper-api/src/main/java/org/bukkit/metadata/LazyMetadataValue.java

@@ -5,6 +5,8 @@ import java.util.concurrent.Callable;
 
 import org.apache.commons.lang.Validate;
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * The LazyMetadataValue class implements a type of metadata that is not
@@ -31,7 +33,7 @@ public class LazyMetadataValue extends MetadataValueAdapter {
      *     value.
      * @param lazyValue the lazy value assigned to this metadata value.
      */
-    public LazyMetadataValue(Plugin owningPlugin, Callable<Object> lazyValue) {
+    public LazyMetadataValue(@NotNull Plugin owningPlugin, @NotNull Callable<Object> lazyValue) {
         this(owningPlugin, CacheStrategy.CACHE_AFTER_FIRST_EVAL, lazyValue);
     }
 
@@ -44,7 +46,7 @@ public class LazyMetadataValue extends MetadataValueAdapter {
      *     value.
      * @param lazyValue the lazy value assigned to this metadata value.
      */
-    public LazyMetadataValue(Plugin owningPlugin, CacheStrategy cacheStrategy, Callable<Object> lazyValue) {
+    public LazyMetadataValue(@NotNull Plugin owningPlugin, @NotNull CacheStrategy cacheStrategy, @NotNull Callable<Object> lazyValue) {
         super(owningPlugin);
         Validate.notNull(cacheStrategy, "cacheStrategy cannot be null");
         Validate.notNull(lazyValue, "lazyValue cannot be null");
@@ -59,10 +61,11 @@ public class LazyMetadataValue extends MetadataValueAdapter {
      * 
      * @param owningPlugin the owning plugin
      */
-    protected LazyMetadataValue(Plugin owningPlugin) {
+    protected LazyMetadataValue(@NotNull Plugin owningPlugin) {
         super(owningPlugin);
     }
 
+    @Nullable
     public Object value() {
         eval();
         Object value = internalValue.get();

paper-api/src/main/java/org/bukkit/metadata/MetadataStore.java

@@ -1,6 +1,7 @@
 package org.bukkit.metadata;
 
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.List;
 
@@ -14,7 +15,7 @@ public interface MetadataStore<T> {
      * @throws IllegalArgumentException If value is null, or the owning plugin
      *     is null
      */
-    public void setMetadata(T subject, String metadataKey, MetadataValue newMetadataValue);
+    public void setMetadata(@NotNull T subject, @NotNull String metadataKey, @NotNull MetadataValue newMetadataValue);
 
     /**
      * Returns all metadata values attached to an object. If multiple plugins
@@ -25,7 +26,8 @@ public interface MetadataStore<T> {
      * @return A list of values, one for each plugin that has set the
      *     requested value.
      */
-    public List<MetadataValue> getMetadata(T subject, String metadataKey);
+    @NotNull
+    public List<MetadataValue> getMetadata(@NotNull T subject, @NotNull String metadataKey);
 
     /**
      * Tests to see if a metadata attribute has been set on an object.
@@ -35,7 +37,7 @@ public interface MetadataStore<T> {
      * @param metadataKey the unique metadata key being queried.
      * @return the existence of the metadataKey within subject.
      */
-    public boolean hasMetadata(T subject, String metadataKey);
+    public boolean hasMetadata(@NotNull T subject, @NotNull String metadataKey);
 
     /**
      * Removes a metadata item owned by a plugin from a subject.
@@ -46,7 +48,7 @@ public interface MetadataStore<T> {
      * @param owningPlugin the plugin attempting to remove a metadata item.
      * @throws IllegalArgumentException If plugin is null
      */
-    public void removeMetadata(T subject, String metadataKey, Plugin owningPlugin);
+    public void removeMetadata(@NotNull T subject, @NotNull String metadataKey, @NotNull Plugin owningPlugin);
 
     /**
      * Invalidates all metadata in the metadata store that originates from the
@@ -56,5 +58,5 @@ public interface MetadataStore<T> {
      * @param owningPlugin the plugin requesting the invalidation.
      * @throws IllegalArgumentException If plugin is null
      */
-    public void invalidateAll(Plugin owningPlugin);
+    public void invalidateAll(@NotNull Plugin owningPlugin);
 }

paper-api/src/main/java/org/bukkit/metadata/MetadataStoreBase.java

@@ -2,6 +2,7 @@ package org.bukkit.metadata;
 
 import org.apache.commons.lang.Validate;
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.*;
 
@@ -30,7 +31,7 @@ public abstract class MetadataStoreBase<T> {
      * @throws IllegalArgumentException If value is null, or the owning plugin
      *     is null
      */
-    public synchronized void setMetadata(T subject, String metadataKey, MetadataValue newMetadataValue) {
+    public synchronized void setMetadata(@NotNull T subject, @NotNull String metadataKey, @NotNull MetadataValue newMetadataValue) {
         Validate.notNull(newMetadataValue, "Value cannot be null");
         Plugin owningPlugin = newMetadataValue.getOwningPlugin();
         Validate.notNull(owningPlugin, "Plugin cannot be null");
@@ -53,7 +54,8 @@ public abstract class MetadataStoreBase<T> {
      *     requested value.
      * @see MetadataStore#getMetadata(Object, String)
      */
-    public synchronized List<MetadataValue> getMetadata(T subject, String metadataKey) {
+    @NotNull
+    public synchronized List<MetadataValue> getMetadata(@NotNull T subject, @NotNull String metadataKey) {
         String key = disambiguate(subject, metadataKey);
         if (metadataMap.containsKey(key)) {
             Collection<MetadataValue> values = metadataMap.get(key).values();
@@ -71,7 +73,7 @@ public abstract class MetadataStoreBase<T> {
      * @param metadataKey the unique metadata key being queried.
      * @return the existence of the metadataKey within subject.
      */
-    public synchronized boolean hasMetadata(T subject, String metadataKey) {
+    public synchronized boolean hasMetadata(@NotNull T subject, @NotNull String metadataKey) {
         String key = disambiguate(subject, metadataKey);
         return metadataMap.containsKey(key);
     }
@@ -87,7 +89,7 @@ public abstract class MetadataStoreBase<T> {
      *     org.bukkit.plugin.Plugin)
      * @throws IllegalArgumentException If plugin is null
      */
-    public synchronized void removeMetadata(T subject, String metadataKey, Plugin owningPlugin) {
+    public synchronized void removeMetadata(@NotNull T subject, @NotNull String metadataKey, @NotNull Plugin owningPlugin) {
         Validate.notNull(owningPlugin, "Plugin cannot be null");
         String key = disambiguate(subject, metadataKey);
         Map<Plugin, MetadataValue> entry = metadataMap.get(key);
@@ -110,7 +112,7 @@ public abstract class MetadataStoreBase<T> {
      * @see MetadataStore#invalidateAll(org.bukkit.plugin.Plugin)
      * @throws IllegalArgumentException If plugin is null
      */
-    public synchronized void invalidateAll(Plugin owningPlugin) {
+    public synchronized void invalidateAll(@NotNull Plugin owningPlugin) {
         Validate.notNull(owningPlugin, "Plugin cannot be null");
         for (Map<Plugin, MetadataValue> values : metadataMap.values()) {
             if (values.containsKey(owningPlugin)) {
@@ -132,5 +134,6 @@ public abstract class MetadataStoreBase<T> {
      * @param metadataKey The name identifying the metadata value.
      * @return a unique metadata key for the given subject.
      */
-    protected abstract String disambiguate(T subject, String metadataKey);
+    @NotNull
+    protected abstract String disambiguate(@NotNull T subject, @NotNull String metadataKey);
 }

paper-api/src/main/java/org/bukkit/metadata/MetadataValue.java

@@ -1,6 +1,8 @@
 package org.bukkit.metadata;
 
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 public interface MetadataValue {
 
@@ -9,6 +11,7 @@ public interface MetadataValue {
      *
      * @return the metadata value.
      */
+    @Nullable
     public Object value();
 
     /**
@@ -65,14 +68,15 @@ public interface MetadataValue {
      *
      * @return the value as a string.
      */
+    @NotNull
     public String asString();
 
     /**
      * Returns the {@link Plugin} that created this metadata item.
      *
-     * @return the plugin that owns this metadata value. This should never be
-     *     null.
+     * @return the plugin that owns this metadata value. Could be null if the plugin was already unloaded.
      */
+    @Nullable
     public Plugin getOwningPlugin();
 
     /**

paper-api/src/main/java/org/bukkit/metadata/MetadataValueAdapter.java

@@ -5,6 +5,8 @@ import java.lang.ref.WeakReference;
 import org.apache.commons.lang.Validate;
 import org.bukkit.plugin.Plugin;
 import org.bukkit.util.NumberConversions;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Optional base class for facilitating MetadataValue implementations.
@@ -16,11 +18,12 @@ import org.bukkit.util.NumberConversions;
 public abstract class MetadataValueAdapter implements MetadataValue {
     protected final WeakReference<Plugin> owningPlugin;
 
-    protected MetadataValueAdapter(Plugin owningPlugin) {
+    protected MetadataValueAdapter(@NotNull Plugin owningPlugin) {
         Validate.notNull(owningPlugin, "owningPlugin cannot be null");
         this.owningPlugin = new WeakReference<Plugin>(owningPlugin);
     }
 
+    @Nullable
     public Plugin getOwningPlugin() {
         return owningPlugin.get();
     }
@@ -66,6 +69,7 @@ public abstract class MetadataValueAdapter implements MetadataValue {
         return value != null;
     }
 
+    @NotNull
     public String asString() {
         Object value = value();
 

paper-api/src/main/java/org/bukkit/metadata/Metadatable.java

@@ -1,6 +1,7 @@
 package org.bukkit.metadata;
 
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.List;
 
@@ -17,7 +18,7 @@ public interface Metadatable {
      * @throws IllegalArgumentException If value is null, or the owning plugin
      *     is null
      */
-    public void setMetadata(String metadataKey, MetadataValue newMetadataValue);
+    public void setMetadata(@NotNull String metadataKey, @NotNull MetadataValue newMetadataValue);
 
     /**
      * Returns a list of previously set metadata values from the implementing
@@ -27,7 +28,8 @@ public interface Metadatable {
      * @return A list of values, one for each plugin that has set the
      *     requested value.
      */
-    public List<MetadataValue> getMetadata(String metadataKey);
+    @NotNull
+    public List<MetadataValue> getMetadata(@NotNull String metadataKey);
 
     /**
      * Tests to see whether the implementing object contains the given
@@ -36,7 +38,7 @@ public interface Metadatable {
      * @param metadataKey the unique metadata key being queried.
      * @return the existence of the metadataKey within subject.
      */
-    public boolean hasMetadata(String metadataKey);
+    public boolean hasMetadata(@NotNull String metadataKey);
 
     /**
      * Removes the given metadata value from the implementing object's
@@ -48,5 +50,5 @@ public interface Metadatable {
      *     other values will be left untouched.
      * @throws IllegalArgumentException If plugin is null
      */
-    public void removeMetadata(String metadataKey, Plugin owningPlugin);
+    public void removeMetadata(@NotNull String metadataKey, @NotNull Plugin owningPlugin);
 }