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

[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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.51%. Comparing base (2728100) to head (52359ba).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #2711      +/-   ##
============================================
+ Coverage     68.32%   68.51%   +0.19%     
  Complexity      656      656              
============================================
  Files           741      739       -2     
  Lines         62158    61161     -997     
  Branches      58571    57574     -997     
============================================
- Hits          42468    41904     -564     
+ Misses        17583    17236     -347     
+ Partials       2107     2021      -86     

Flag	Coverage Δ
java	52.19% <ø> (ø)

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	97.82% <ø> (ø)

... and 41 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.

[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.

[atharvalade]

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.

I've updated the PR to move the examples to the canonical examples/java/ directory instead of foreign/java/examples

[mmodzelewski]

Hey @atharvalade, thanks for the PR. I've left a few comments, please address them.