This is an automated email from the ASF dual-hosted git repository.
divijv pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 43574beb972 KAFKA-15131: Improve RemoteStorageManager exception
handling documentation (#13923)
43574beb972 is described below
commit 43574beb972d47d696e0de077f453b36ce148026
Author: Jorge Esteban Quilcate Otoya <[email protected]>
AuthorDate: Fri Jun 30 07:37:48 2023 -0500
KAFKA-15131: Improve RemoteStorageManager exception handling documentation
(#13923)
Reviewers: Divij Vaidya <[email protected]>, Satish Duggana
<[email protected]>, Luke Chen <[email protected]>
---
.../server/log/remote/storage/RemoteStorageManager.java | 16 +++++++++++-----
1 file changed, 11 insertions(+), 5 deletions(-)
diff --git
a/storage/api/src/main/java/org/apache/kafka/server/log/remote/storage/RemoteStorageManager.java
b/storage/api/src/main/java/org/apache/kafka/server/log/remote/storage/RemoteStorageManager.java
index 6231d8e25c1..cc26109969c 100644
---
a/storage/api/src/main/java/org/apache/kafka/server/log/remote/storage/RemoteStorageManager.java
+++
b/storage/api/src/main/java/org/apache/kafka/server/log/remote/storage/RemoteStorageManager.java
@@ -75,6 +75,9 @@ public interface RemoteStorageManager extends Configurable,
Closeable {
* <p>
* Invoker of this API should always send a unique id as part of {@link
RemoteLogSegmentMetadata#remoteLogSegmentId()}
* even when it retries to invoke this method for the same log segment
data.
+ * <p>
+ * This operation is expected to be idempotent. If a copy operation is
retried and there is existing content already written,
+ * it should be overwritten, and do not throw {@link
RemoteStorageException}
*
* @param remoteLogSegmentMetadata metadata about the remote log segment.
* @param logSegmentData data to be copied to tiered storage.
@@ -92,7 +95,7 @@ public interface RemoteStorageManager extends Configurable,
Closeable {
* @param startPosition start position of log segment to be
read, inclusive.
* @return input stream of the requested log segment data.
* @throws RemoteStorageException if there are any errors while
fetching the desired segment.
- * @throws RemoteResourceNotFoundException when there are no resources
associated with the given remoteLogSegmentMetadata.
+ * @throws RemoteResourceNotFoundException the requested log segment is
not found in the remote storage.
*/
InputStream fetchLogSegment(RemoteLogSegmentMetadata
remoteLogSegmentMetadata,
int startPosition) throws
RemoteStorageException;
@@ -107,7 +110,7 @@ public interface RemoteStorageManager extends Configurable,
Closeable {
* @param endPosition end position of log segment to be read,
inclusive.
* @return input stream of the requested log segment data.
* @throws RemoteStorageException if there are any errors while
fetching the desired segment.
- * @throws RemoteResourceNotFoundException when there are no resources
associated with the given remoteLogSegmentMetadata.
+ * @throws RemoteResourceNotFoundException the requested log segment is
not found in the remote storage.
*/
InputStream fetchLogSegment(RemoteLogSegmentMetadata
remoteLogSegmentMetadata,
int startPosition,
@@ -120,7 +123,10 @@ public interface RemoteStorageManager extends
Configurable, Closeable {
* @param indexType type of the index to be fetched for the
segment.
* @return input stream of the requested index.
* @throws RemoteStorageException if there are any errors while
fetching the index.
- * @throws RemoteResourceNotFoundException when there are no resources
associated with the given remoteLogSegmentMetadata.
+ * @throws RemoteResourceNotFoundException the requested index is not
found in the remote storage
+ * (e.g. Transaction index may not exist because segments created prior to
version 2.8.0 will not have transaction index associated with them.).
+ * The caller of this function are encouraged to re-create the indexes
from the segment
+ * as the suggested way of handling this error if the index is expected to
be existed.
*/
InputStream fetchIndex(RemoteLogSegmentMetadata remoteLogSegmentMetadata,
IndexType indexType) throws RemoteStorageException;
@@ -130,11 +136,11 @@ public interface RemoteStorageManager extends
Configurable, Closeable {
* successful if this call returns successfully without any errors. It
will throw {@link RemoteStorageException} if
* there are any errors in deleting the file.
* <p>
+ * This operation is expected to be idempotent. If resources are not
found, it is not expected to
+ * throw {@link RemoteResourceNotFoundException} as it may be already
removed from a previous attempt.
*
* @param remoteLogSegmentMetadata metadata about the remote log segment
to be deleted.
- * @throws RemoteResourceNotFoundException if the requested resource is
not found
* @throws RemoteStorageException if there are any storage
related errors occurred.
- * @throws RemoteResourceNotFoundException when there are no resources
associated with the given remoteLogSegmentMetadata.
*/
void deleteLogSegmentData(RemoteLogSegmentMetadata
remoteLogSegmentMetadata) throws RemoteStorageException;
}
\ No newline at end of file
