Add nullability annotations

Author: afranken

pom.xml

@@ -612,6 +612,7 @@
           <version>${kotlin.version}</version>
           <extensions>true</extensions>
           <configuration>
+            <javaParameters>true</javaParameters>
             <args>
               <arg>-Xjsr305=strict</arg> <!-- Enable strict mode for JSR-305 annotations -->
             </args>

server/pom.xml

@@ -79,6 +79,10 @@
       <groupId>org.apache.commons</groupId>
       <artifactId>commons-lang3</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+    </dependency>
     <!-- Test Dependencies -->
     <dependency>
       <groupId>org.apache.httpcomponents</groupId>

server/src/main/java/com/adobe/testing/s3mock/service/BucketService.java

@@ -63,6 +63,7 @@
 import java.util.Objects;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
+import org.jspecify.annotations.Nullable;
 import software.amazon.awssdk.utils.http.SdkHttpUtils;
 
 public class BucketService {
@@ -99,8 +100,11 @@ public boolean doesBucketExist(String bucketName) {
     return bucketStore.doesBucketExist(bucketName);
   }
 
-  public ListAllMyBucketsResult listBuckets(Region bucketRegion, String continuationToken,
-                                            Integer maxBuckets, String prefix) {
+  public ListAllMyBucketsResult listBuckets(
+      @Nullable Region bucketRegion,
+      @Nullable String continuationToken,
+      Integer maxBuckets,
+      @Nullable String prefix) {
     String nextContinuationToken = null;
     var normalizedPrefix = prefix == null ? "" : prefix;
 
@@ -139,12 +143,13 @@ public Bucket getBucket(String bucketName) {
     return Bucket.from(bucketStore.getBucketMetadata(bucketName));
   }
 
-  public Bucket createBucket(String bucketName,
+  public Bucket createBucket(
+      String bucketName,
       boolean objectLockEnabled,
       ObjectOwnership objectOwnership,
       String bucketRegion,
-      BucketInfo bucketInfo,
-      LocationInfo locationInfo) {
+      @Nullable BucketInfo bucketInfo,
+      @Nullable LocationInfo locationInfo) {
     return Bucket.from(
         bucketStore.createBucket(bucketName,
             objectLockEnabled,
@@ -213,8 +218,9 @@ public ObjectLockConfiguration getObjectLockConfiguration(String bucketName) {
     }
   }
 
-  public void setBucketLifecycleConfiguration(String bucketName,
-      BucketLifecycleConfiguration configuration) {
+  public void setBucketLifecycleConfiguration(
+      String bucketName,
+      @Nullable BucketLifecycleConfiguration configuration) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     bucketStore.storeBucketLifecycleConfiguration(bucketMetadata, configuration);
   }
@@ -233,7 +239,7 @@ public BucketLifecycleConfiguration getBucketLifecycleConfiguration(String bucke
     }
   }
 
-  public List<S3Object> getS3Objects(String bucketName, String prefix) {
+  public List<S3Object> getS3Objects(String bucketName, @Nullable String prefix) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuids = bucketStore.lookupKeysInBucket(prefix, bucketName);
     return uuids
@@ -300,13 +306,14 @@ public ListVersionsResult listVersions(String bucketName,
     );
   }
 
-  public ListBucketResultV2 listObjectsV2(String bucketName,
-      String prefix,
-      String delimiter,
-      String encodingType,
-      String startAfter,
+  public ListBucketResultV2 listObjectsV2(
+      String bucketName,
+      @Nullable String prefix,
+      @Nullable String delimiter,
+      @Nullable String encodingType,
+      @Nullable String startAfter,
       Integer maxKeys,
-      String continuationToken,
+      @Nullable String continuationToken,
       boolean fetchOwner) {
 
     if (maxKeys == 0) {
@@ -396,8 +403,13 @@ public ListBucketResultV2 listObjectsV2(String bucketName,
   }
 
   @Deprecated(since = "2.12.2", forRemoval = true)
-  public ListBucketResult listObjectsV1(String bucketName, String prefix, String delimiter,
-      String marker, String encodingType, Integer maxKeys) {
+  public ListBucketResult listObjectsV1(
+      String bucketName,
+      @Nullable String prefix,
+      @Nullable String delimiter,
+      @Nullable String marker,
+      @Nullable String encodingType,
+      Integer maxKeys) {
 
     if (maxKeys == 0) {
       return new ListBucketResult(List.of(), List.of(), null,  encodingType,
@@ -470,11 +482,10 @@ public Map<String, String> bucketLocationHeaders(BucketMetadata bucketMetadata)
   }
 
   public BucketMetadata verifyBucketExists(String bucketName) {
-    var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
-    if (bucketMetadata == null) {
+    if (!bucketStore.doesBucketExist(bucketName)) {
       throw NO_SUCH_BUCKET;
     } else {
-      return bucketMetadata;
+      return bucketStore.getBucketMetadata(bucketName);
     }
   }
 

server/src/main/java/com/adobe/testing/s3mock/service/MultipartService.java

@@ -48,6 +48,7 @@
 import java.util.Objects;
 import java.util.UUID;
 import java.util.stream.Collectors;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpRange;
@@ -65,6 +66,7 @@ public MultipartService(BucketStore bucketStore, MultipartStore multipartStore)
     this.multipartStore = multipartStore;
   }
 
+  @Nullable
   public String putPart(
       String bucketName,
       String key,
@@ -81,6 +83,7 @@ public String putPart(
         path, encryptionHeaders);
   }
 
+  @Nullable
   public CopyPartResult copyPart(
       String bucketName,
       String key,
@@ -115,6 +118,7 @@ public CopyPartResult copyPart(
     }
   }
 
+  @Nullable
   public ListPartsResult getMultipartUploadParts(
       String bucketName,
       String key,
@@ -170,6 +174,7 @@ public void abortMultipartUpload(String bucketName, String key, String uploadId)
     }
   }
 
+  @Nullable
   public CompleteMultipartUploadResult completeMultipartUpload(
       String bucketName,
       String key,
@@ -237,7 +242,7 @@ public ListMultipartUploadsResult listMultipartUploads(
       String encodingType,
       String keyMarker,
       Integer maxUploads,
-      String prefix,
+      @Nullable String prefix,
       String uploadIdMarker
   ) {
     String nextKeyMarker = null;

server/src/main/java/com/adobe/testing/s3mock/service/ObjectService.java

@@ -51,6 +51,7 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -66,6 +67,7 @@ public ObjectService(BucketStore bucketStore, ObjectStore objectStore) {
     this.objectStore = objectStore;
   }
 
+  @Nullable
   public S3ObjectMetadata copyS3Object(String sourceBucketName,
       String sourceKey,
       String versionId,
@@ -148,7 +150,7 @@ public DeleteResult deleteObjects(String bucketName, Delete delete) {
     return response;
   }
 
-  public boolean deleteObject(String bucketName, String key, String versionId) {
+  public boolean deleteObject(String bucketName, String key, @Nullable String versionId) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var id = bucketMetadata.getID(key);
     if (id == null) {
@@ -162,31 +164,34 @@ public boolean deleteObject(String bucketName, String key, String versionId) {
     }
   }
 
-  public void setObjectTags(String bucketName, String key, String versionId, List<Tag> tags) {
+  /**
+   * <a href="https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions">API Reference</a>.
+   */
+  public void setObjectTags(String bucketName, String key, @Nullable String versionId, @Nullable List<Tag> tags) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuid = bucketMetadata.getID(key);
     objectStore.storeObjectTags(bucketMetadata, uuid, versionId, tags);
   }
 
-  public void setLegalHold(String bucketName, String key, String versionId, LegalHold legalHold) {
+  public void setLegalHold(String bucketName, String key, @Nullable String versionId, LegalHold legalHold) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuid = bucketMetadata.getID(key);
     objectStore.storeLegalHold(bucketMetadata, uuid, versionId, legalHold);
   }
 
-  public void setAcl(String bucketName, String key, String versionId, AccessControlPolicy policy) {
+  public void setAcl(String bucketName, String key, @Nullable String versionId, AccessControlPolicy policy) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuid = bucketMetadata.getID(key);
     objectStore.storeAcl(bucketMetadata, uuid, versionId, policy);
   }
 
-  public AccessControlPolicy getAcl(String bucketName, String key, String versionId) {
+  public AccessControlPolicy getAcl(String bucketName, String key, @Nullable String versionId) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuid = bucketMetadata.getID(key);
     return objectStore.readAcl(bucketMetadata, uuid, versionId);
   }
 
-  public void setRetention(String bucketName, String key, String versionId, Retention retention) {
+  public void setRetention(String bucketName, String key, @Nullable String versionId, Retention retention) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuid = bucketMetadata.getID(key);
     objectStore.storeRetention(bucketMetadata, uuid, versionId, retention);
@@ -209,7 +214,7 @@ public void verifyMd5(Path input, String contentMd5) {
     }
   }
 
-  public void verifyMd5(InputStream inputStream, String contentMd5) {
+  public void verifyMd5(InputStream inputStream, @Nullable String contentMd5) {
     if (contentMd5 != null) {
       var md5 = DigestUtil.base64Digest(inputStream);
       if (!md5.equals(contentMd5)) {
@@ -255,9 +260,9 @@ public void verifyObjectMatching(
 
   public void verifyObjectMatching(
       List<String> match,
-      List<Instant> matchLastModifiedTime,
-      List<Long> matchSize,
-      S3ObjectMetadata s3ObjectMetadata) {
+      @Nullable List<Instant> matchLastModifiedTime,
+      @Nullable List<Long> matchSize,
+      @Nullable S3ObjectMetadata s3ObjectMetadata) {
 
     verifyObjectMatching(match, null, null, null, s3ObjectMetadata);
     if (s3ObjectMetadata != null) {
@@ -277,11 +282,11 @@ public void verifyObjectMatching(
   }
 
   public void verifyObjectMatching(
-      List<String> match,
-      List<String> noneMatch,
-      List<Instant> ifModifiedSince,
-      List<Instant> ifUnmodifiedSince,
-      S3ObjectMetadata s3ObjectMetadata) {
+      @Nullable List<String> match,
+      @Nullable List<String> noneMatch,
+      @Nullable List<Instant> ifModifiedSince,
+      @Nullable List<Instant> ifUnmodifiedSince,
+      @Nullable S3ObjectMetadata s3ObjectMetadata) {
     if (s3ObjectMetadata == null) {
       // object does not exist, so we can skip the rest of the checks.
       return;
@@ -324,7 +329,7 @@ public void verifyObjectMatching(
     }
   }
 
-  public S3ObjectMetadata verifyObjectExists(String bucketName, String key, String versionId) {
+  public S3ObjectMetadata verifyObjectExists(String bucketName, String key, @Nullable String versionId) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuid = bucketMetadata.getID(key);
     if (uuid == null) {
@@ -339,7 +344,8 @@ public S3ObjectMetadata verifyObjectExists(String bucketName, String key, String
     return s3ObjectMetadata;
   }
 
-  public S3ObjectMetadata getObject(String bucketName, String key, String versionId) {
+  @Nullable
+  public S3ObjectMetadata getObject(String bucketName, String key, @Nullable String versionId) {
     var bucketMetadata = bucketStore.getBucketMetadata(bucketName);
     var uuid = bucketMetadata.getID(key);
     if (uuid == null) {
@@ -348,8 +354,7 @@ public S3ObjectMetadata getObject(String bucketName, String key, String versionI
     return objectStore.getS3ObjectMetadata(bucketMetadata, uuid, versionId);
   }
 
-  public S3ObjectMetadata verifyObjectLockConfiguration(String bucketName, String key,
-      String versionId) {
+  public S3ObjectMetadata verifyObjectLockConfiguration(String bucketName, String key, @Nullable String versionId) {
     var s3ObjectMetadata = verifyObjectExists(bucketName, key, versionId);
     var noLegalHold = s3ObjectMetadata.legalHold() == null;
     var noRetention = s3ObjectMetadata.retention() == null;

server/src/main/java/com/adobe/testing/s3mock/service/ServiceBase.java

@@ -38,6 +38,7 @@
 import java.util.function.Function;
 import java.util.function.UnaryOperator;
 import org.apache.commons.lang3.tuple.Pair;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpHeaders;
@@ -51,7 +52,7 @@ public void verifyChecksum(Path path, String checksum, ChecksumAlgorithm checksu
     DigestUtil.verifyChecksum(checksum, checksumFor, checksumAlgorithm);
   }
 
-  public Pair<Path, String> toTempFile(InputStream inputStream, HttpHeaders httpHeaders) {
+  public Pair<Path, @Nullable String> toTempFile(InputStream inputStream, HttpHeaders httpHeaders) {
     try {
       var tempFile = Files.createTempFile("ObjectService", "toTempFile");
       try (var os = Files.newOutputStream(tempFile);
@@ -70,7 +71,7 @@ public Pair<Path, String> toTempFile(InputStream inputStream, HttpHeaders httpHe
     }
   }
 
-  public Pair<Path, String> toTempFile(InputStream inputStream) {
+  public Pair<Path, @Nullable String> toTempFile(InputStream inputStream) {
     try {
       var tempFile = Files.createTempFile("ObjectService", "toTempFile");
       try (var os = Files.newOutputStream(tempFile)) {
@@ -96,7 +97,7 @@ static <T> List<T> mapContents(
   static <T> List<T> filterBy(
       List<T> contents,
       Function<T, String> function,
-      String compareTo
+      @Nullable String compareTo
   ) {
     if (isNotEmpty(compareTo)) {
       return contents
@@ -111,7 +112,7 @@ static <T> List<T> filterBy(
   static <T> List<T> filterBy(
       List<T> contents,
       Function<T, Integer> function,
-      Integer compareTo
+      @Nullable Integer compareTo
   ) {
     if (compareTo != null) {
       return contents
@@ -126,7 +127,7 @@ static <T> List<T> filterBy(
   static <T> List<T> filterBy(
       List<T> contents,
       Function<T, String> function,
-      List<String> prefixes
+      @Nullable List<String> prefixes
   ) {
     if (prefixes != null && !prefixes.isEmpty()) {
       return contents
@@ -154,8 +155,8 @@ static <T> List<T> filterBy(
    * @param function the function to apply on a content to extract the value to collapse the prefixes on
    */
   static <T> List<String> collapseCommonPrefixes(
-      String queryPrefix,
-      String delimiter,
+      @Nullable String queryPrefix,
+      @Nullable String delimiter,
       List<T> contents,
       Function<T, String> function
   ) {

server/src/main/java/com/adobe/testing/s3mock/service/package-info.java

@@ -0,0 +1,20 @@
+/*
+ *  Copyright 2017-2025 Adobe.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *          http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+@NullMarked
+package com.adobe.testing.s3mock.service;
+
+import org.jspecify.annotations.NullMarked;