Improve documents for Handle Exceptions #897
Conversation
| @@ -56,9 +56,11 @@ public interface DistributedTransactionManager { | |||
| * Begins a new transaction. | |||
| * | |||
| * @return {@link DistributedTransaction} | |||
| * @throws TransactionNotFoundException if beginning the transaction fails, but it's retryable. | |||
There was a problem hiding this comment.
| * @throws TransactionNotFoundException if beginning the transaction fails, but it's retryable. | |
| * @throws TransactionNotFoundException if the transaction fails to start. |
I removed but it's retryable because I feel it's a bit redundant with the next sentence.
Ditto for the others.
There was a problem hiding this comment.
I think removing but it's retryable may make the statement sound unsure about the difference from the TransactionException. So, how about removing the next sentence?
There was a problem hiding this comment.
OK, then, how about something like this to make things clear?
@throws TransactionNotFoundException if the transaction fails to start due to xxx. You can retry the transaction.
@throws TransactionException if the transaction fails to start due to yyy. You cannot retry the transaction.
Can we say something for xxx and yyy?
There was a problem hiding this comment.
Thank you for the suggestion.
Actually, it's hard to say concrete reasons for TransactionNotFoundException because it only occurs in ScalarDB Cluster.
So, how about some thing like the following?
@throws TransactionNotFoundException if the transaction fails to start due to retryable reasons. You can retry the transaction.
@throws TransactionException if the transaction fails to start.
There was a problem hiding this comment.
How about this?
@throws TransactionNotFoundException if the transaction fails to start due to transient faults. You can retry the transaction.
@throws TransactionException if the transaction fails to start due to transient or nontransient faults. You can try retrying the transaction, but you may not be able to start the transaction due to nontransient faults.
There was a problem hiding this comment.
Thank you for the suggestion! Fixed in 59d8433. Please take a look when you have time!
docs/api-guide.md
Outdated
| @@ -781,6 +785,10 @@ public class Sample { | |||
| } | |||
| ``` | |||
|
|
|||
| The `begin()` API could throw `TransactionException` and `TransactionNotFoundException`. | |||
| If you catch `TransactionException`, it indicates some failure (e.g., database failure and network error) happens during a transaction, so you should cancel the transaction or retry the transaction after the failure/error is fixed. | |||
There was a problem hiding this comment.
| If you catch `TransactionException`, it indicates some failure (e.g., database failure and network error) happens during a transaction, so you should cancel the transaction or retry the transaction after the failure/error is fixed. | |
| If you catch `TransactionException`, it indicates some failure (e.g., database failure and network error) happens during the transaction, so you should cancel the transaction or retry the transaction after the failure or error is fixed. |
Co-authored-by: Vincent Guilpain <vincent.guilpain@scalar-labs.com>
docs/api-guide.md
Outdated
| @@ -781,19 +785,29 @@ public class Sample { | |||
| } | |||
| ``` | |||
|
|
|||
| The `begin()` API could throw `TransactionException` and `TransactionNotFoundException`. | |||
| If you catch `TransactionException`, it indicates some failure (e.g., database failure and network error) happens during the transaction, so you should cancel the transaction or retry the transaction after the failure or error is fixed. | |||
| If you catch `TransactionNotFoundException`, it indicates the transaction is not found, but it's retryable, so you can retry the transaction. | |||
There was a problem hiding this comment.
it indicates the transaction is not found
[minor] Is it possible to describe possible causes of the exception?
There was a problem hiding this comment.
Actually, this doesn't happens with ScalarDB, but It can happen with ScalarDB Cluster. So, I can't describe possible causes here... :(
| @@ -56,9 +56,11 @@ public interface DistributedTransactionManager { | |||
| * Begins a new transaction. | |||
| * | |||
| * @return {@link DistributedTransaction} | |||
| * @throws TransactionNotFoundException if beginning the transaction fails, but it's retryable. | |||
There was a problem hiding this comment.
How about this?
@throws TransactionNotFoundException if the transaction fails to start due to transient faults. You can retry the transaction.
@throws TransactionException if the transaction fails to start due to transient or nontransient faults. You can try retrying the transaction, but you may not be able to start the transaction due to nontransient faults.
Please take a look!