Add Javadoc, feature matrix, and runnable authenticated example (async + sync wrapper)

[saitejareddy05]

Prerequisites

• Search the current open issues

What are you trying to do that currently feels hard or impossible?

What is hard or impossible today
Discovering the public API surface, understanding which MCP Toolbox features the Java SDK supports, and getting a working authenticated example are currently difficult:

• No published Javadoc or API reference to explore public classes and method contracts.
• README notes “not at parity” with other SDKs but provides no feature matrix or roadmap.
• Examples are minimal and do not show a complete authenticated workflow (token caching, refresh, error handling) or an ergonomic synchronous wrapper.

End goal (specific use-case)
A new user should be able to:

1. Browse generated Javadoc for all public classes and methods.
2. Consult FEATURES.md to see implemented vs planned features (auth flows, streaming, retries, Graal support, etc.).
3. Run a runnable example that demonstrates:
   • ADC and OIDC authentication flows,
   • an AuthTokenGetter with caching and refresh,
   • async usage (CompletableFuture) with error handling,
   • a small blocking wrapper (ExampleUsageSync) that avoids exposing .join() to user code,
   • instructions to run locally and in Cloud Run/CI.
4. Run a lightweight WireMock integration test that validates basic request/response behavior.

---

Suggested Solution

Proposed deliverables (can be split into multiple PRs)

1. FEATURES.md — root-level file with a table of features and parity status.

   • Columns: Feature, Status (Implemented / In progress / Planned), Notes / Parity.
   • Rows should include: Authentication (ADC, OIDC), Request binding, Streaming, Retries/backoff, Rate limiting, GraalVM native support, Sync wrapper, Examples, Tests.

2. examples/authenticated-tool/ — runnable example:

   • AuthTokenGetter.java — token caching + refresh logic with unit tests.
   • ExampleUsageAsync.java — demonstrates async calls, retries, and error handling.
   • ExampleUsageSync.java — small blocking wrapper that calls the async client and returns results without exposing .join() to users.
   • README.md — how to run locally (ADC), in Cloud Run, and in CI.

3. Javadoc CI — GitHub Actions job:

   • Run mvn javadoc:javadoc on merges to main.
   • Publish to GitHub Pages or attach as a build artifact for PRs.
   • Add a Javadoc link or badge to the README.

4. WireMock integration test:

   • Minimal test that starts WireMock, configures expected endpoints, runs the example client, and asserts requests and responses.

5. README update — link to FEATURES.md, examples, and published Javadoc.

Implementation notes

• Keep examples dependency-light (use WireMock for tests; avoid heavy frameworks).
• Provide a small AuthTokenGetter interface in examples that can be swapped for ADC or OIDC implementations.
• Add unit tests for token caching logic and builder configuration.

---

Alternatives Considered

What to include

• Short list of concrete alternatives (e.g., “read source code”, “use another language SDK and translate examples”, “run local javadoc”).
• For each alternative, one or two sentences about limitations (maintenance burden, poor ergonomics, missing Java idioms, extra setup).
• A clear statement of why the proposed feature is preferable (reduces onboarding friction, centralizes docs, provides idiomatic Java examples, CI automation).

Why maintainers care
This helps reviewers understand tradeoffs and avoid duplicating effort. It also shows you’ve considered lower‑effort options and can justify the requested work.

Additional Details

What to include

• Links or references to related issues or PRs (IDs or short descriptions).
• Screenshots, command outputs, or example snippets that illustrate the problem or the desired behavior.
• Non‑functional requirements (CI expectations, publishing cadence for docs, compatibility targets like Java 17/21, Graal notes).
• Suggested acceptance criteria or test ideas (e.g., “add WireMock integration test that validates auth flow”).

Why maintainers care
Extra details reduce back‑and‑forth, speed review, and make it easier to split the work into actionable PRs. Well‑scoped additional details increase the chance the issue will be picked up and implemented.

[saitejareddy05]

mam /sir can you confirm to work on this for creation of pull request for the above isses and also can help me to add anything new to this issue