docs: annotate all Option factory methods with their Nullability boun…

…ds (#1775)

Update all option factory methods to explicitly state their Nullability bounds. All methods which take non-primitive parameters are @nonnull, and will be published in the javadocs.

Add new tests to explicitly verify null argument validation.

All factory methods now check their args for nullness, instead of depending on implicit checking.

google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java

@@ -44,6 +44,7 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * An object in Google Cloud Storage. A {@code Blob} object includes the {@code BlobId} instance,
@@ -128,7 +129,7 @@ public static BlobSourceOption metagenerationNotMatch() {
      * blob.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobSourceOption decryptionKey(Key key) {
+    public static BlobSourceOption decryptionKey(@NonNull Key key) {
       return new BlobSourceOption(UnifiedOpts.decryptionKey(key));
     }
 
@@ -139,7 +140,7 @@ public static BlobSourceOption decryptionKey(Key key) {
      * @param key the AES256 encoded in base64
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobSourceOption decryptionKey(String key) {
+    public static BlobSourceOption decryptionKey(@NonNull String key) {
       return new BlobSourceOption(UnifiedOpts.decryptionKey(key));
     }
 
@@ -148,7 +149,7 @@ public static BlobSourceOption decryptionKey(String key) {
      * bucket has requester_pays flag enabled.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobSourceOption userProject(String userProject) {
+    public static BlobSourceOption userProject(@NonNull String userProject) {
       return new BlobSourceOption(UnifiedOpts.userProject(userProject));
     }
 

google-cloud-storage/src/main/java/com/google/cloud/storage/Bucket.java

@@ -44,6 +44,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * A Google cloud storage bucket.
@@ -93,7 +94,7 @@ public static BucketSourceOption metagenerationNotMatch() {
      * with 'requester_pays' flag.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BucketSourceOption userProject(String userProject) {
+    public static BucketSourceOption userProject(@NonNull String userProject) {
       return new BucketSourceOption(UnifiedOpts.userProject(userProject));
     }
 
@@ -142,7 +143,7 @@ private BlobTargetOption(ObjectTargetOpt opt) {
 
     /** Returns an option for specifying blob's predefined ACL configuration. */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobTargetOption predefinedAcl(Storage.PredefinedAcl acl) {
+    public static BlobTargetOption predefinedAcl(Storage.@NonNull PredefinedAcl acl) {
       return new BlobTargetOption(UnifiedOpts.predefinedAcl(acl));
     }
 
@@ -201,7 +202,7 @@ public static BlobTargetOption metagenerationNotMatch(long metageneration) {
      * blob.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobTargetOption encryptionKey(Key key) {
+    public static BlobTargetOption encryptionKey(@NonNull Key key) {
       return new BlobTargetOption(UnifiedOpts.encryptionKey(key));
     }
 
@@ -212,7 +213,7 @@ public static BlobTargetOption encryptionKey(Key key) {
      * @param key the AES256 encoded in base64
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobTargetOption encryptionKey(String key) {
+    public static BlobTargetOption encryptionKey(@NonNull String key) {
       return new BlobTargetOption(UnifiedOpts.encryptionKey(key));
     }
 
@@ -222,7 +223,7 @@ public static BlobTargetOption encryptionKey(String key) {
      * @param kmsKeyName the KMS key resource id
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobTargetOption kmsKeyName(String kmsKeyName) {
+    public static BlobTargetOption kmsKeyName(@NonNull String kmsKeyName) {
       return new BlobTargetOption(UnifiedOpts.kmsKeyName(kmsKeyName));
     }
 
@@ -231,7 +232,7 @@ public static BlobTargetOption kmsKeyName(String kmsKeyName) {
      * with 'requester_pays' flag.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobTargetOption userProject(String userProject) {
+    public static BlobTargetOption userProject(@NonNull String userProject) {
       return new BlobTargetOption(UnifiedOpts.userProject(userProject));
     }
 
@@ -263,7 +264,7 @@ private BlobWriteOption(ObjectTargetOpt opt) {
 
     /** Returns an option for specifying blob's predefined ACL configuration. */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobWriteOption predefinedAcl(Storage.PredefinedAcl acl) {
+    public static BlobWriteOption predefinedAcl(Storage.@NonNull PredefinedAcl acl) {
       return new BlobWriteOption(UnifiedOpts.predefinedAcl(acl));
     }
 
@@ -322,7 +323,7 @@ public static BlobWriteOption metagenerationNotMatch(long metageneration) {
      * fail if blobs' data MD5 hash does not match the provided value.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobWriteOption md5Match(String md5) {
+    public static BlobWriteOption md5Match(@NonNull String md5) {
       return new BlobWriteOption(UnifiedOpts.md5Match(md5));
     }
 
@@ -331,7 +332,7 @@ public static BlobWriteOption md5Match(String md5) {
      * will fail if blobs' data CRC32C checksum does not match the provided value.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobWriteOption crc32cMatch(String crc32c) {
+    public static BlobWriteOption crc32cMatch(@NonNull String crc32c) {
       return new BlobWriteOption(UnifiedOpts.crc32cMatch(crc32c));
     }
 
@@ -340,7 +341,7 @@ public static BlobWriteOption crc32cMatch(String crc32c) {
      * blob.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobWriteOption encryptionKey(Key key) {
+    public static BlobWriteOption encryptionKey(@NonNull Key key) {
       return new BlobWriteOption(UnifiedOpts.encryptionKey(key));
     }
 
@@ -351,7 +352,7 @@ public static BlobWriteOption encryptionKey(Key key) {
      * @param key the AES256 encoded in base64
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobWriteOption encryptionKey(String key) {
+    public static BlobWriteOption encryptionKey(@NonNull String key) {
       return new BlobWriteOption(UnifiedOpts.encryptionKey(key));
     }
 
@@ -360,7 +361,7 @@ public static BlobWriteOption encryptionKey(String key) {
      * with 'requester_pays' flag.
      */
     @TransportCompatibility({Transport.HTTP, Transport.GRPC})
-    public static BlobWriteOption userProject(String userProject) {
+    public static BlobWriteOption userProject(@NonNull String userProject) {
       return new BlobWriteOption(UnifiedOpts.userProject(userProject));
     }
 

google-cloud-storage/src/main/java/com/google/cloud/storage/BucketInfo.java

@@ -1061,7 +1061,7 @@ public static DeleteLifecycleAction newDeleteAction() {
        * @param storageClass The new storage class to use when conditions are met for this action.
        */
       public static SetStorageClassLifecycleAction newSetStorageClassAction(
-          StorageClass storageClass) {
+          @NonNull StorageClass storageClass) {
         return new SetStorageClassLifecycleAction(storageClass);
       }
 
@@ -1080,7 +1080,7 @@ public static LifecycleAction newAbortIncompleteMPUploadAction() {
        * generally not be used, instead use the supported actions, and upgrade the library if necessary
        * to get new supported actions.
        */
-      public static LifecycleAction newLifecycleAction(String actionType) {
+      public static LifecycleAction newLifecycleAction(@NonNull String actionType) {
         return new LifecycleAction(actionType);
       }
     }