From dde4fcc3f631134aecf52cdd62c05f5c33124f53 Mon Sep 17 00:00:00 2001
From: lizhimins <707364882@qq.com>
Date: Tue, 26 Mar 2024 11:20:22 +0800
Subject: [PATCH] Add interface comment for query offset operation with
 boundary type (#7965)

---
 .../tieredstore/file/FlatFileInterface.java   | 25 +++++++++++++++----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/tieredstore/src/main/java/org/apache/rocketmq/tieredstore/file/FlatFileInterface.java b/tieredstore/src/main/java/org/apache/rocketmq/tieredstore/file/FlatFileInterface.java
index 773f3cbecac..619470fbc27 100644
--- a/tieredstore/src/main/java/org/apache/rocketmq/tieredstore/file/FlatFileInterface.java
+++ b/tieredstore/src/main/java/org/apache/rocketmq/tieredstore/file/FlatFileInterface.java
@@ -120,11 +120,26 @@ public interface FlatFileInterface {
     CompletableFuture<ByteBuffer> getConsumeQueueAsync(long consumeQueueOffset, int count);
 
     /**
-     * Gets the offset in the consume queue by timestamp and boundary type
-     *
-     * @param timestamp    search time
-     * @param boundaryType lower or upper to decide boundary
-     * @return Returns the offset of the message
+     * Gets the start offset in the consume queue based on the timestamp and boundary type.
+     * The consume queues consist of ordered units, and their storage times are non-decreasing
+     * sequence. If the specified message exists, it returns the offset of either the first
+     * or last message, depending on the boundary type. If the specified message does not exist,
+     * it returns the offset of the next message as the pull offset. For example:
+     * ------------------------------------------------------------
+     *   store time   : 40, 50, 50, 50, 60, 60, 70
+     *   queue offset : 10, 11, 12, 13, 14, 15, 16
+     * ------------------------------------------------------------
+     *   query timestamp | boundary | result (reason)
+     *         35        |    -     |   10 (minimum offset)
+     *         45        |    -     |   11 (next offset)
+     *         50        |   lower  |   11
+     *         50        |   upper  |   13
+     *         60        |    -     |   14 (default to lower)
+     *         75        |    -     |   17 (maximum offset + 1)
+     * ------------------------------------------------------------
+     * @param timestamp    The search time
+     * @param boundaryType 'lower' or 'upper' to determine the boundary
+     * @return Returns the offset of the message in the consume queue
      */
     CompletableFuture<Long> getQueueOffsetByTimeAsync(long timestamp, BoundaryType boundaryType);