Document ApiException throw behavior for AppHelper node queries - #2804
Draft
rootkiller6788 wants to merge 1 commit into
Draft
Document ApiException throw behavior for AppHelper node queries#2804rootkiller6788 wants to merge 1 commit into
rootkiller6788 wants to merge 1 commit into
Conversation
connectedNodes() and connectedAndInstalledNodes throw ApiException when the Wearable API is not available on the device, but this was not documented, surprising library users (see issue google#2596). Point callers to isAvailable() so they can guard against the crash.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
connectedAndInstalledNodesandconnectedNodes()both hit the Wearable API (CapabilityClient/NodeClient) via.await(). When the Wearable API is not available on a device, these calls throwApiException: 17: API: Wearable.API is not available on this device, but this throw behavior was completely undocumented. Library users discovered this the hard way (see #2596) because the failure surfaces as an opaque GMS stack trace with no Horologist frame in sight.isAvailable()exists precisely to guard against this, but nothing in the doc pointed users to it.Change
Add
@throws ApiExceptionKDoc to the two public entry points (connectedNodes()and the abstractconnectedAndInstalledNodesproperty), both referencingisAvailable()as the way to check before use. No behavioral change — documentation only.Verification
CapabilityClient/NodeClientGMS tasks viaawait(), which fail withApiExceptionwhen the API is unavailable (confirmed by the stack trace inconnectedAndInstalledNodesthrows into the outer scope when API is not available #2596).ApiExceptionis already imported in the file.Fixes #2596