Organize exceptions thrown

[twyatt]

IOException chosen for failures where an I/O operation did not succeed. It is expected that library users will catch these exceptions and decide if operation should be retried or if more extreme measures should be taken (e.g. reconnect prior to retrying).

Closes #81.

core

Class	Base Exception
RemoteException	Exception
ConnectionLostException	IOException
GattStatusException	IOException
OutOfOrderGattCallbackException	IllegalStateException

• OutOfOrderGattCallbackException should never occur. This failure is not recoverable and the behavior of future requests is undefined. Library user should allow app to crash or re-establish connect (to reset callback state). If this exception is ever encountered it should be reported so it may be investigated.
• RemoteException occurs when the Android system fails to execute a request, it is unlikely that retrying the operation will succeed until the user intervenes (e.g. turns on BLE).

keep-alive

Class	Base Exception
NotReadyException	IOException

throw

Class	Base Exception
GattStatusException (core)	IOException
RemoteException	Exception
ConnectionLostException	IOException

📓 Notes

Since SharedFlow is not yet officially released, this branch was developed against internally built Coroutines artifacts; this PR will be merged into internal branch (see #86 for details).

[cedrickcooke]

Should these constructors be internal like the other exceptions?

[twyatt]

Yes, but...
This exception is also thrown from throw module.

I tried utilizing friend-paths (to give throw module access to internal definitions in core) but could not get it working. 😢

Spent about 3 hours trying to get the friend paths working before giving up and just accepting this little bit of cruft on the public API surface.

[cedrickcooke]

I really wish Kotlin had way more visibility modifiers. Something like Android's @RestrictTo but at a language level.

[sdonn3]

lgtm!

[twyatt]

Small update: This PR was brought into develop via a fast-forwarding of develop to internal (that was dropped). So some slight modifications of the squashed commit may exist in the final commit that landed in develop.