root
/
kafka
mirror of https://github.com/apache/kafka.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

KAFKA-15131: Improve RemoteStorageManager exception handling documentation (#13923) 

Reviewers: Divij Vaidya <diviv@amazon.com>, Satish Duggana <satishd@apache.org>, Luke Chen <showuon@gmail.com>
This commit is contained in:
Jorge Esteban Quilcate Otoya 2023-06-30 07:37:48 -05:00 committed by GitHub
parent 1f4cbc5d53
commit 43574beb97
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
storage/api/src/main/java/org/apache/kafka/server/log/remote/storage/RemoteStorageManager.java
View File

@ -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;
}