Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve API consistency and docs. #228

Merged
merged 5 commits into from
Sep 3, 2020
Merged

Improve API consistency and docs. #228

merged 5 commits into from
Sep 3, 2020

Conversation

quelgar
Copy link
Contributor

@quelgar quelgar commented Jul 6, 2020

I started a branch where I tried to cleanup the APIs, make things more consistent and add some docs. I belatedly realised it was going to be a rather large PR. I'm happy to rollback individual elements if there's no agreement on them.

  • Change most APIs to use IOException as the error type instead of Exception. Non-IO exceptions are now considered defects as they only occur due to misuse of the API.
  • Similarly change incorrect Buffer usage errors to be defects instead of failures.

I found in practice I would always turn the usage mistake exceptions into defects anyway.

  • The Async* classes still use Exception for the error type for now, as the NIO Javadocs are vague as to what kind of exceptions to expect from these.
  • Make the Buffer-based read/write methods public where they aren't already, according to the "unopinionated" principle.
  • Rename various read and write methods so they match the underlying NIO methods. Seems clearer, but I don't feel strongly about it.
  • Add various Scaladocs (more still needed).
  • Use Option to indicate end-of-stream when reading, instead of -1 magic value. Changed all read methods to indicate end-of-stream by failing with java.io.EOFException. The eofOption method can be used to turn an EOFException failure into a success with None if the user wants that.

@quelgar quelgar force-pushed the quelgar/api-cleanup branch 3 times, most recently from 029583f to 81e77c4 Compare July 21, 2020 10:03
quelgar added 4 commits August 5, 2020 18:19
* Change most APIs to use `IOException` as the error type instead
  of `Exception`. Non-IO exceptions are now considered defects as
  they only occur due to misuse of the API.
* Similarly change incorrect `Buffer` usage errors to be defects
  instead of failures.
* The `Async*` classes still use `Exception` for the error type
  for now, as the NIO Javadocs are vague as to what kind of
  exceptions to expect from these.
* Rename various read and write methods so they match the
  underlying NIO methods. Seems clearer.
* Add various Scaladocs (more still needed).
* Use `Option` to indicate end-of-stream when reading,
  instead of `-1` magic value.
End-of-stream is now handled in a consistent way across all read APIs.
If a read encounters end-of-stream, the effect will fail with a
`java.io.EOFException`.
@quelgar quelgar force-pushed the quelgar/api-cleanup branch from 81e77c4 to a303c28 Compare August 5, 2020 08:22
@jdegoes jdegoes merged commit af08eac into master Sep 3, 2020
@jdegoes
Copy link
Member

jdegoes commented Sep 3, 2020

Thanks for your work on this!

@jdegoes jdegoes deleted the quelgar/api-cleanup branch September 3, 2020 12:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants