Igniters,
I would like to start the discussion about error handling in Ignite 3 and
how we can improve it compared to Ignite 2.
The error handling in Ignite 2 was not very good because of generic
CacheException thrown on almost any occasion, having deeply nested root
cause and often containing no useful information on further steps to fix
the issue.
I aim to fix it by introducing some rules on error handling.
*Public exception structure.*
A public exception must have an error code, a cause, and an action.
* The code - the combination of 2 byte scope id and 2 byte error number
within the module. This allows up to 2^16 errors for each scope, which
should be enough. The error code string representation can look like
RFT-0001 or TBL-0001
* The cause - short string description of an issue, readable by user. This
can have dynamic parameters depending on the error type for better user
experience, like "Can't write a snapshot, no space left on device {0}"
* The action - steps for a user to resolve error situation described in the
documentation in the corresponding error section, for example "Clean up
disk space and retry the operation".
Common errors should have their own scope, for example IGN-0001
All public methods throw only unchecked
org.apache.ignite.lang.IgniteException containing aforementioned fields.
Each public method must have a section in the javadoc with a list of all
possible error codes for this method.
A good example with similar structure can be found here [1]
*Async timeouts.*
Because almost all API methods in Ignite 3 are async, they all will have a
configurable default timeout and can complete with timeout error if a
computation is not finished in time, for example if a response has not been
yet received.
I suggest to complete the async op future with TimeoutException in this
case to make it on par with synchronous execution using future.get, which
will throw java.util.concurrent.TimeoutException on timeout.
For reference, see java.util.concurrent.CompletableFuture#orTimeout
No special error code should be used for this scenario.
*Internal exceptions hierarchy.*
All internal exceptions should extend
org.apache.ignite.internal.lang.IgniteInternalException for checked
exceptions and
org.apache.ignite.internal.lang.IgniteInternalCheckedException for
unchecked exceptions.
Thoughts ?
[1] https://docs.oracle.com/cd/B10501_01/server.920/a96525/preface.htm
--
Best regards,
Alexei Scherbakov
