docs(java): add async client JavaDoc and usage guide (#2231)

[atharvalade]

Which issue does this PR close?

Closes #2231

Rationale

The async client had minimal documentation — interfaces lacked JavaDoc, there was no usage guide, and developers had no reference for CompletableFuture patterns, error handling, or migration from the blocking client.

What changed?

The async client interfaces (StreamsClient, MessagesClient, TopicsClient, UsersClient, ConsumerGroupsClient) and AsyncIggyTcpClient had sparse or missing JavaDoc. Developers had to read the source to understand method contracts, parameter semantics, and exception behavior.

Added comprehensive JavaDoc to all public async APIs with @param, @return, @throws, and @see cross-references. Created ASYNC_CLIENT.md covering getting started, connection management, error handling, CompletableFuture chaining patterns, three example applications (high-throughput producer, backpressure consumer, error recovery), performance characteristics (async vs blocking, thread pool sizing), and a step-by-step migration guide. Added package-info.java for both async packages.

Local Execution

• PassedcompileJava, checkstyleMain, spotlessCheck, and javadoc all pass with zero errors
• Pre-commit hooks not ran prek is Rust-specific, this PR is Java/docs only

AI Usage

1. Claude (Opus 4.6) via Cursor IDE
2. The documentation content is AI-generated. Used AI to write JavaDoc, the ASYNC_CLIENT.md guide, and example code snippets. Also used AI to cross-reference every {@link}, @see, and @throws tag against the actual source code, and to verify all code examples in the guide use correct method signatures, return types, and accessor names from the real API.
3. Verified by running a clean build from scratch (clean + compileJava + checkstyleMain + spotlessCheck + javadoc) all pass. Manually audited every JavaDoc reference against the source (e.g., confirmed CompressionAlgorithm.None is an enum constant not a method, confirmed record accessors like stream.id() and polled.messages() match actual field names, confirmed all 11 exception types in the error handling table exist in the hierarchy).
4. Yes

[codecov]

Codecov Report

❌ Patch coverage is 0% with 352 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.10%. Comparing base (5306a91) to head (7dac198).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
...in/java/org/apache/iggy/example/AsyncConsumer.java	0.00%	129 Missing ⚠️
...in/java/org/apache/iggy/example/AsyncProducer.java	0.00%	92 Missing ⚠️
...java/org/apache/iggy/example/BlockingConsumer.java	0.00%	73 Missing ⚠️
...java/org/apache/iggy/example/BlockingProducer.java	0.00%	58 Missing ⚠️

❌ Your patch check has failed because the patch coverage (0.00%) is below the target coverage (50.00%). You can increase the patch coverage or adjust the target coverage.

❗ There is a different number of reports uploaded between BASE (5306a91) and HEAD (7dac198). Click for more details.

HEAD has 1 upload less than BASE

Flag	BASE (5306a91)	HEAD (7dac198)
rust	1	0

Additional details and impacted files

@@              Coverage Diff              @@
##             master    #2711       +/-   ##
=============================================
- Coverage     69.03%   47.10%   -21.93%     
- Complexity        0      637      +637     
=============================================
  Files           571      167      -404     
  Lines         55525     4201    -51324     
  Branches      55525      285    -55240     
=============================================
- Hits          38332     1979    -36353     
+ Misses        15318     2137    -13181     
+ Partials       1875       85     -1790     

Flag	Coverage Δ
java	47.10% <0.00%> (?)
rust	?

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...a/org/apache/iggy/client/async/MessagesClient.java	0.00% <ø> (ø)
...va/org/apache/iggy/client/async/StreamsClient.java	0.00% <ø> (ø)
...ache/iggy/client/async/tcp/AsyncIggyTcpClient.java	63.04% <ø> (ø)
...java/org/apache/iggy/example/BlockingProducer.java	0.00% <0.00%> (ø)
...java/org/apache/iggy/example/BlockingConsumer.java	0.00% <0.00%> (ø)
...in/java/org/apache/iggy/example/AsyncProducer.java	0.00% <0.00%> (ø)
...in/java/org/apache/iggy/example/AsyncConsumer.java	0.00% <0.00%> (ø)

... and 731 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[hubcio]

tbh i'm not fan of this document. why not incorporate these into examples/java? we want the docs to be as close to code as possible.

i.e. have separate examples for blocking / nonblocking java client, etc.

what do you think?

[atharvalade]

hmm, that's a good point. tbh, I am actually not sure why I didn't think of this in the first place. Plan is to drop the standalone markdown doc and move the examples into an actual examples/ module with compilable Java apps (async producer, async consumer, blocking equivalents). The JavaDoc on the interfaces stays as-is since that's where it belongs.

Will push an updated version shortly.

[atharvalade]

I pushed the new version, let me know if that's better!

[slbotbm]

Examples for Java already exist in iggy/examples/java. If these examples show new functions to the user, they could be moved to the examples directory. If they do not, documentation could be added to the existing examples. Let's wait for others to review as well.