Cleanup JavaDoc for stores.

afranken · afranken · commit 024319a63cae · 2025-06-15T00:43:55.000+02:00
The API doc and function signatures describe what the functions do,
let's describe what they do differently from what is described in the
API instead of stating the obvious.
diff --git a/server/src/main/java/com/adobe/testing/s3mock/store/BucketStore.java b/server/src/main/java/com/adobe/testing/s3mock/store/BucketStore.java
@@ -65,11 +65,6 @@ public BucketStore(File rootFolder,
     this.objectMapper = objectMapper;
   }
 
-  /**
-   * Lists all BucketMetadata managed by this store.
-   *
-   * @return List of all BucketMetadata.
-   */
   public List<BucketMetadata> listBuckets() {
     return findBucketPaths()
         .stream()
@@ -78,13 +73,6 @@ public List<BucketMetadata> listBuckets() {
         .toList();
   }
 
-  /**
-   * Retrieves BucketMetadata identified by its name.
-   *
-   * @param bucketName name of the bucket to be retrieved
-   *
-   * @return the BucketMetadata or null if not found
-   */
   public BucketMetadata getBucketMetadata(String bucketName) {
     try {
       var metaFilePath = getMetaFilePath(bucketName);
@@ -99,13 +87,6 @@ public BucketMetadata getBucketMetadata(String bucketName) {
     }
   }
 
-  /**
-   * Adds key to a bucket.
-   *
-   * @param key        the key to add
-   * @param bucketName name of the bucket to be retrieved
-   * @return UUID assigned to key
-   */
   public synchronized UUID addKeyToBucket(String key, String bucketName) {
     synchronized (lockStore.get(bucketName)) {
       var bucketMetadata = getBucketMetadata(bucketName);
@@ -115,13 +96,6 @@ public synchronized UUID addKeyToBucket(String key, String bucketName) {
     }
   }
 
-  /**
-   * Look up keys by prefix in a bucket.
-   *
-   * @param prefix     the prefix to filter on
-   * @param bucketName name of the bucket to be retrieved
-   * @return List of UUIDs of keys matching the prefix
-   */
   public List<UUID> lookupKeysInBucket(String prefix, String bucketName) {
     var bucketMetadata = getBucketMetadata(bucketName);
     var normalizedPrefix = prefix == null ? "" : prefix;
@@ -135,13 +109,6 @@ public List<UUID> lookupKeysInBucket(String prefix, String bucketName) {
     }
   }
 
-  /**
-   * Removes key from a bucket.
-   *
-   * @param key        the key to remove
-   * @param bucketName name of the bucket to be retrieved
-   * @return true if key existed and was removed
-   */
   public synchronized boolean removeFromBucket(String key, String bucketName) {
     synchronized (lockStore.get(bucketName)) {
       var bucketMetadata = getBucketMetadata(bucketName);
@@ -151,11 +118,6 @@ public synchronized boolean removeFromBucket(String key, String bucketName) {
     }
   }
 
-  /**
-   * Searches for folders in the rootFolder.
-   *
-   * @return List of found Folders.
-   */
   private List<Path> findBucketPaths() {
     var bucketPaths = new ArrayList<Path>();
     try (var stream = Files.newDirectoryStream(rootFolder.toPath(), Files::isDirectory)) {
@@ -169,16 +131,6 @@ private List<Path> findBucketPaths() {
     return bucketPaths;
   }
 
-  /**
-   * Creates a new bucket.
-   *
-   * @param bucketName of the Bucket to be created.
-   *
-   * @return the newly created Bucket.
-   *
-   * @throws IllegalStateException if the bucket cannot be created or the bucket already exists but
-   *        is not a directory.
-   */
   public BucketMetadata createBucket(String bucketName,
       boolean objectLockEnabled,
       ObjectOwnership objectOwnership,
@@ -215,10 +167,6 @@ public BucketMetadata createBucket(String bucketName,
    * Checks if the specified bucket exists. Amazon S3 buckets are named in a global namespace; use
    * this method to determine if a specified bucket name already exists, and therefore can't be used
    * to create a new bucket.
-   *
-   * @param bucketName of the bucket to check for existence
-   *
-   * @return true if Bucket exists
    */
   public boolean doesBucketExist(String bucketName) {
     return getBucketMetadata(bucketName) != null;
@@ -253,14 +201,6 @@ public void storeBucketLifecycleConfiguration(BucketMetadata metadata,
     }
   }
 
-
-  /**
-   * Checks if the specified bucket exists and if it is empty.
-   *
-   * @param bucketName of the bucket to check for existence
-   *
-   * @return true if Bucket is empty
-   */
   public boolean isBucketEmpty(String bucketName) {
     var bucketMetadata = getBucketMetadata(bucketName);
     if (bucketMetadata != null) {
@@ -270,13 +210,6 @@ public boolean isBucketEmpty(String bucketName) {
     }
   }
 
-  /**
-   * Deletes a Bucket and all of its contents.
-   *
-   * @param bucketName of the bucket to be deleted.
-   *
-   * @return true if deletion succeeded.
-   */
   public boolean deleteBucket(String bucketName) {
     try {
       synchronized (lockStore.get(bucketName)) {
@@ -296,8 +229,6 @@ public boolean deleteBucket(String bucketName) {
 
   /**
    * Used to load metadata for all buckets when S3Mock starts.
-   * @param bucketNames names of existing buckets.
-   * @return ID of the loaded buckets.
    */
   List<UUID> loadBuckets(List<String> bucketNames) {
     var objectIds = new ArrayList<UUID>();
diff --git a/server/src/main/java/com/adobe/testing/s3mock/store/MultipartStore.java b/server/src/main/java/com/adobe/testing/s3mock/store/MultipartStore.java
@@ -59,9 +59,6 @@
 import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpRange;
 
-/**
- * Stores parts and their metadata created in S3Mock.
- */
 public class MultipartStore extends StoreBase {
   private static final Logger LOG = LoggerFactory.getLogger(MultipartStore.class);
   private static final String PART_SUFFIX = ".part";
@@ -81,19 +78,6 @@ public MultipartStore(ObjectStore objectStore, ObjectMapper objectMapper) {
     this.objectMapper = objectMapper;
   }
 
-  /**
-   * Prepares everything to store an object uploaded as multipart upload.
-   *
-   * @param bucket       Bucket to upload object in
-   * @param key          object to upload
-   * @param id           ID of the object
-   * @param contentType  the content type
-   * @param storeHeaders various headers to store
-   * @param owner        owner of the upload
-   * @param initiator    initiator of the upload
-   * @param userMetadata custom metadata
-   * @return upload result
-   */
   public MultipartUpload createMultipartUpload(
       BucketMetadata bucket,
       String key,
@@ -141,22 +125,16 @@ public MultipartUpload createMultipartUpload(
     return upload;
   }
 
-  /**
-   * Lists all not-yet completed parts of multipart uploads in a bucket.
-   *
-   * @param bucketMetadata the bucket to use as a filter
-   * @param prefix the prefix use as a filter
-   *
-   * @return the list of not-yet completed multipart uploads.
-   */
   public List<MultipartUpload> listMultipartUploads(BucketMetadata bucketMetadata, String prefix) {
     var multipartsFolder = getMultipartsFolder(bucketMetadata);
     if (!multipartsFolder.toFile().exists()) {
       return Collections.emptyList();
     }
     try (var paths = Files.newDirectoryStream(multipartsFolder)) {
-      return Streams.of(paths)
-          .map(path -> {
+      return Streams
+          .of(paths)
+          .map(
+              path -> {
                 var fileName = path.getFileName().toString();
                 return getUploadMetadata(bucketMetadata, fileName).upload();
               }
@@ -173,12 +151,6 @@ public MultipartUploadInfo getMultipartUploadInfo(BucketMetadata bucketMetadata,
     return getUploadMetadata(bucketMetadata, uploadId);
   }
 
-  /**
-   * Get MultipartUpload, if it was not completed.
-   * @param uploadId id of the upload
-   *
-   * @return the multipart upload, if it exists, throws IllegalArgumentException otherwise.
-   */
   public MultipartUpload getMultipartUpload(BucketMetadata bucketMetadata, String uploadId) {
     var uploadMetadata = getUploadMetadata(bucketMetadata, uploadId);
     if (uploadMetadata != null) {
@@ -188,13 +160,6 @@ public MultipartUpload getMultipartUpload(BucketMetadata bucketMetadata, String
     }
   }
 
-  /**
-   * Aborts the upload.
-   *
-   * @param bucket to which was uploaded
-   * @param id of the object
-   * @param uploadId of the upload
-   */
   public void abortMultipartUpload(BucketMetadata bucket, UUID id, String uploadId) {
     var multipartUploadInfo = getMultipartUploadInfo(bucket, uploadId);
     if (multipartUploadInfo != null) {
@@ -209,17 +174,6 @@ public void abortMultipartUpload(BucketMetadata bucket, UUID id, String uploadId
     }
   }
 
-  /**
-   * Uploads a part of a multipart upload.
-   *
-   * @param bucket                    in which to upload
-   * @param id                      of the object to upload
-   * @param uploadId                      id of the upload
-   * @param partNumber                    number of the part to store
-   * @param path                     file data to be stored
-   *
-   * @return the md5 digest of this part
-   */
   public String putPart(BucketMetadata bucket,
       UUID id,
       String uploadId,
@@ -231,17 +185,6 @@ public String putPart(BucketMetadata bucket,
     return hexDigest(encryptionHeaders.get(X_AMZ_SERVER_SIDE_ENCRYPTION_AWS_KMS_KEY_ID), file);
   }
 
-  /**
-   * Completes a Multipart Upload for the given ID.
-   *
-   * @param bucket in which to upload.
-   * @param key of the object to upload.
-   * @param id id of the object
-   * @param uploadId id of the upload.
-   * @param parts to concatenate.
-   *
-   * @return etag of the uploaded file.
-   */
   public CompleteMultipartUploadResult completeMultipartUpload(
       BucketMetadata bucket,
       String key,
@@ -348,13 +291,6 @@ private String checksumFor(List<Path> paths, MultipartUploadInfo uploadInfo) {
     return null;
   }
 
-  /**
-   * Get all multipart upload parts.
-   * @param bucket name of the bucket
-   * @param id object ID
-   * @param uploadId upload identifier
-   * @return List of Parts
-   */
   public List<Part> getMultipartUploadParts(BucketMetadata bucket, UUID id, String uploadId) {
     var partsPath = getPartsFolder(bucket, uploadId);
     try (var directoryStream = newDirectoryStream(partsPath,
@@ -377,20 +313,6 @@ public List<Part> getMultipartUploadParts(BucketMetadata bucket, UUID id, String
     }
   }
 
-  /**
-   * Copies the range, define by from/to, from the S3 Object, identified by the given key to given
-   * destination into the given bucket.
-   *
-   * @param bucket The source Bucket.
-   * @param id Identifies the S3 Object.
-   * @param copyRange Byte range to copy. Optional.
-   * @param partNumber The part to copy.
-   * @param destinationBucket The Bucket the target object (will) reside in.
-   * @param destinationId The target object ID.
-   * @param uploadId id of the upload.
-   *
-   * @return etag of the uploaded file.
-   */
   public String copyPart(BucketMetadata bucket,
       UUID id,
       HttpRange copyRange,
@@ -407,11 +329,6 @@ public String copyPart(BucketMetadata bucket,
         createPartFile(destinationBucket, destinationId, uploadId, partNumber), versionId);
   }
 
-  /**
-   * Returns an InputStream containing InputStreams from each path element.
-   * @param paths the paths to read
-   * @return an InputStream containing all data.
-   */
   private static InputStream toInputStream(List<Path> paths) {
     var result = new ArrayList<InputStream>();
     for (var path: paths) {
diff --git a/server/src/main/java/com/adobe/testing/s3mock/store/ObjectStore.java b/server/src/main/java/com/adobe/testing/s3mock/store/ObjectStore.java
