(james-project) 03/03: ISSUE-4182 Adapt review suggestions

[hq...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

quantranhong1999 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git

commit d2e1415019fd5c52fa520b1d92d07f14a909a59e
Author: Quan Tran <hq...@linagora.com>
AuthorDate: Thu May 7 14:19:09 2026 +0700

    ISSUE-4182 Adapt review suggestions
---
 docs/modules/servers/partials/architecture/blobstore.adoc   |  6 ++++++
 .../src/main/java/org/apache/james/blob/api/BlobStore.java  | 13 +++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/docs/modules/servers/partials/architecture/blobstore.adoc b/docs/modules/servers/partials/architecture/blobstore.adoc
index dca52fc490..fb4ef523d1 100644
--- a/docs/modules/servers/partials/architecture/blobstore.adoc
+++ b/docs/modules/servers/partials/architecture/blobstore.adoc
@@ -16,6 +16,12 @@ Most James components use `BlobStore`, which is responsible for saving content
 and returning a `BlobId`. `BlobStoreDAO` is the lower-level persistence contract:
 it stores, reads, lists, and deletes blobs for a given `BucketName` and `BlobId`.
 
+A `BlobStore` exposes a default logical bucket through `getDefaultBucketName()`.
+Callers can explicitly pass another `BucketName` when they need to store data in
+another logical bucket. More advanced organization rules inside a logical bucket
+are not part of the generic `BlobStore` contract; callers need to model them
+explicitly or provide a custom `BlobStore` implementation.
+
 Cross-cutting storage features can be composed around this DAO contract. For
 example, deduplication decides blob identifiers at the `BlobStore` level, while
 wrappers such as compression or encryption can transform payloads and metadata
diff --git a/server/blob/blob-api/src/main/java/org/apache/james/blob/api/BlobStore.java b/server/blob/blob-api/src/main/java/org/apache/james/blob/api/BlobStore.java
index 8d5101e0db..0493e27743 100644
--- a/server/blob/blob-api/src/main/java/org/apache/james/blob/api/BlobStore.java
+++ b/server/blob/blob-api/src/main/java/org/apache/james/blob/api/BlobStore.java
@@ -27,6 +27,19 @@ import com.google.common.io.ByteSource;
 
 import reactor.util.function.Tuple2;
 
+/**
+ * High-level James blob storage abstraction.
+ *
+ * <p>A {@link BlobStore} stores binary payloads in a James logical {@link BucketName}
+ * and returns {@link BlobId} references. A configured {@link BlobStore} exposes a default
+ * logical bucket through {@link #getDefaultBucketName()}.</p>
+ *
+ * <p>A {@link BucketName} is a James-specific logical bucket. Each storage connector decides how this logical
+ * bucket is represented in its backend. It should not be conflated with an S3 bucket name and does not have to map one-to-one
+ * to a physical bucket.</p>
+ *
+ * <p>See {@code docs/modules/servers/partials/architecture/blobstore.adoc} for more details.</p>
+ */
 public interface BlobStore {
     String DEFAULT_BUCKET_NAME_QUALIFIER = "defaultBucket";
 


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org