Reduce number of exceptions thrown

[twyatt]

Instead, we should favor nullable return types or sealed classes.

http://www.douevencode.com/articles/2018-09/kotlin-error-handling/ summarizes it well.

Exceptions currently (develop branch) being thrown:

core

• RemoteException
• ConnectionLostException
• OutOfOrderGattCallbackException
• GattErrorStatusException

keep-alive

• NotReadyException

throw

• GattStatusException
• RemoteException
• ConnectionLostException

[twyatt]

Investigating this further, Roman Elizarov provided a great decision chart:

1. Are callers of your API supposed to handle failures is some specific way on each call site or are they supposed to handle them globally together with other failures (crash app, write to log, show error dialog, etc)? If only globally - use exceptions, otherwise see below
2. Do callers need additional domain-specific data about failure to handle it (failure position, failure type, etc) or just an indication that an operation has failed? If just an indication of failure - use nullable types, otherwise see below
3. For locally-handled failures with domain-specific additional failure data create a domain-specific sealed class hierarchy to represent successful and failed results with the corresponding data vals.

P.S. Sometimes it varies by caller of your API, so extremely widely-used libraries might have several versions of the same function for different uses (see String.toInt and String.toIntOrNull in the standard library for example).

https://kotlinlang.slack.com/archives/C0922A726/p1536388784000100?thread_ts=1536360062.000100&cid=C0922A726

[twyatt]

Further guidance:

https://kotlin.christmas/2019/17

[twyatt]

Opted to organize the exceptions thrown to make it clearer which exceptions are recoverable (#84).

May revisit/consider domain-specific Result returns in a later major version.

[twyatt]

Exceptions have been updated and changes are in 0.8.0 release.