Skip to content

Commit 98582d9

Browse files
authored
docs: add extras module documentation and Roq sitemap/diagram plugins (a2aproject#962)
* docs: add extras module documentation and Roq sitemap/diagram plugins Add a new Extras section to the docs site with an overview landing page and dedicated subpages for HTTP Clients (Vert.x, Android), Storage & Persistence (JPA Task Store, Push Notification Config Store), Replicated Queue Manager, and OpenTelemetry. Add the Extras entry to the sidebar navigation menu. Enable the Roq sitemap and diagram plugins with a sitemap.xml template.
1 parent 7aa5c01 commit 98582d9

8 files changed

Lines changed: 884 additions & 0 deletions

File tree

‎docs/content/extras.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Extras
3+
description: Optional add-ons for the A2A Java SDK including alternative HTTP clients, database-backed stores, distributed queue replication, and OpenTelemetry observability.
4+
layout: page
5+
---
6+
7+
# Extras
8+
9+
The A2A Java SDK ships with sensible defaults — an in-memory task store, an in-memory push notification config store, a single-instance queue manager, and a JDK HttpClient. The **extras** modules are drop-in replacements that swap these defaults for production-grade alternatives.
10+
11+
All extras use **Java SPI** or **CDI alternative** discovery, so adding the dependency is typically all you need — no code changes required.
12+
13+
## BOM
14+
15+
Import the extras BOM to manage versions:
16+
17+
```xml
18+
<dependencyManagement>
19+
<dependencies>
20+
<dependency>
21+
<groupId>org.a2aproject.sdk</groupId>
22+
<artifactId>a2a-java-extras-bom</artifactId>
23+
<version>$\{org.a2aproject.sdk.version}</version>
24+
<type>pom</type>
25+
<scope>import</scope>
26+
</dependency>
27+
</dependencies>
28+
</dependencyManagement>
29+
```
30+
31+
## [HTTP Clients](/extras/http-clients)
32+
33+
Alternative `A2AHttpClient` implementations. The **Vert.x HTTP Client** (`a2a-java-sdk-http-client-vertx`) replaces the default JDK HttpClient with a reactive, non-blocking Vert.x WebClient — recommended for Quarkus, reactive frameworks, and high-throughput scenarios. An **Android HTTP Client** (`a2a-java-sdk-http-client-android`) is also available for mobile applications.
34+
35+
## [Storage & Persistence](/extras/storage)
36+
37+
JPA-backed replacements for the in-memory stores, providing database persistence for production and load-balanced deployments. Includes a **JPA Task Store** (`a2a-java-extras-task-store-database-jpa`) and a **JPA Push Notification Config Store** (`a2a-java-extras-push-notification-config-store-database-jpa`). Both use Jakarta Persistence API (JPA 3.0+) and share the same datasource configuration.
38+
39+
## [Replicated Queue Manager](/extras/replicated-queue-manager)
40+
41+
Replaces the default `InMemoryQueueManager` with event replication across multiple A2A server instances via message brokers. Required for multi-instance deployments. The core module (`a2a-java-queue-manager-replicated-core`) pairs with a MicroProfile Reactive Messaging strategy (`a2a-java-queue-manager-replication-mp-reactive`) supporting Apache Kafka, Pulsar, or AMQP. You can also write your own `ReplicationStrategy`.
42+
43+
## [OpenTelemetry](/extras/opentelemetry)
44+
45+
Distributed tracing, metrics, and context propagation for A2A servers and clients using OpenTelemetry. The server module (`a2a-java-sdk-opentelemetry-server`) adds automatic span creation for all protocol methods with context propagation across async boundaries. Client modules (`a2a-java-sdk-opentelemetry-client`, `a2a-java-sdk-opentelemetry-client-propagation`) instrument A2A client operations.
Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: HTTP Clients
3+
description: Alternative HTTP client implementations for the A2A Java SDK, including Vert.x WebClient for reactive applications and an Android-specific client.
4+
layout: page
5+
---
6+
7+
# HTTP Clients
8+
9+
The A2A SDK uses an `A2AHttpClient` abstraction for all HTTP communication — fetching agent cards, making transport calls, and SSE streaming. By default, the SDK uses a JDK 11+ HttpClient implementation. These extras provide alternative implementations.
10+
11+
## Vert.x HTTP Client
12+
13+
Replaces the default `JdkA2AHttpClient` with a [Vert.x WebClient](https://vertx.io/docs/vertx-web-client/java/)-based implementation (`VertxA2AHttpClient`) for reactive, non-blocking HTTP communication.
14+
15+
### When to Use
16+
17+
**Recommended for:**
18+
19+
- Quarkus applications (Vert.x is already included)
20+
- Reactive applications using Vert.x or reactive frameworks
21+
- High-throughput scenarios with many concurrent requests
22+
- Applications requiring efficient SSE streaming
23+
- Cloud-native deployments optimizing for resource usage
24+
25+
**Not needed for** simple, low-volume applications or environments where JDK HttpClient performs adequately.
26+
27+
### What It Solves
28+
29+
| | JDK HttpClient | Vert.x WebClient |
30+
|--|----------------|-------------------|
31+
| **I/O model** | Platform threads, blocking | Event loop, non-blocking |
32+
| **Memory** | Higher (one thread per connection) | Lower (shared event loop) |
33+
| **HTTP/2** | Manual configuration | Automatic ALPN negotiation |
34+
| **Reactive integration** | Requires bridging | Native |
35+
36+
### 1. Add Dependency
37+
38+
```xml
39+
<dependency>
40+
<groupId>org.a2aproject.sdk</groupId>
41+
<artifactId>a2a-java-sdk-http-client-vertx</artifactId>
42+
</dependency>
43+
```
44+
45+
For non-Quarkus environments, also add `vertx-web-client`:
46+
47+
```xml
48+
<dependency>
49+
<groupId>io.vertx</groupId>
50+
<artifactId>vertx-web-client</artifactId>
51+
</dependency>
52+
```
53+
54+
### 2. Automatic Discovery (No Code Changes)
55+
56+
The `VertxA2AHttpClientProvider` has **priority 100** (vs. 0 for the JDK client). The SDK's `A2AHttpClientFactory` uses `ServiceLoader` to discover and select the highest-priority provider available:
57+
58+
```java
59+
// No changes needed — A2A SDK automatically uses VertxA2AHttpClient
60+
A2ACardResolver resolver = A2ACardResolver.builder().baseUrl("http://localhost:9999").build();
61+
AgentCard card = resolver.getAgentCard(); // Uses Vert.x under the hood
62+
63+
Client client = Client.builder(card)
64+
.withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
65+
.build();
66+
```
67+
68+
If Vert.x classes are not on the classpath, the provider returns priority `-1` and the SDK falls back to the JDK HttpClient.
69+
70+
### Usage Examples
71+
72+
#### GET Request
73+
74+
```java
75+
try (A2AHttpClient client = A2AHttpClientFactory.create()) {
76+
A2AHttpResponse response = client.createGet()
77+
.url("https://api.example.com/data")
78+
.addHeader("Authorization", "Bearer token")
79+
.get();
80+
81+
if (response.success()) {
82+
System.out.println(response.body());
83+
}
84+
}
85+
```
86+
87+
#### POST Request with JSON Body
88+
89+
```java
90+
try (A2AHttpClient client = A2AHttpClientFactory.create()) {
91+
A2AHttpResponse response = client.createPost()
92+
.url("https://api.example.com/submit")
93+
.addHeader("Content-Type", "application/json")
94+
.body("{\"key\":\"value\"}")
95+
.post();
96+
97+
System.out.println("Status: " + response.status());
98+
}
99+
```
100+
101+
#### Server-Sent Events (SSE) Streaming
102+
103+
```java
104+
try (A2AHttpClient client = A2AHttpClientFactory.create()) {
105+
CompletableFuture<Void> future = client.createGet()
106+
.url("https://api.example.com/stream")
107+
.getAsyncSSE(
108+
message -> System.out.println("Received: " + message),
109+
error -> error.printStackTrace(),
110+
() -> System.out.println("Stream complete")
111+
);
112+
113+
// Do other work while streaming...
114+
future.join();
115+
}
116+
```
117+
118+
### CDI / Quarkus Integration
119+
120+
In Quarkus or other CDI environments, the `VertxA2AHttpClient` automatically discovers and reuses the CDI-managed `Vertx` instance so that your entire application shares the same event loop.
121+
122+
For non-CDI environments, you can share a Vert.x instance manually:
123+
124+
```java
125+
Vertx vertx = Vertx.vertx();
126+
127+
try {
128+
try (VertxA2AHttpClient client = new VertxA2AHttpClient(vertx)) {
129+
A2AHttpResponse response = client.createGet()
130+
.url("https://example.com")
131+
.get();
132+
}
133+
} finally {
134+
vertx.close();
135+
}
136+
```
137+
138+
### Lifecycle Management
139+
140+
| Usage | Behavior on close |
141+
|-------|--------------------|
142+
| Standalone (`new VertxA2AHttpClient()`) | Both `WebClient` and `Vertx` are closed |
143+
| CDI/Quarkus (`new VertxA2AHttpClient(injectedVertx)`) | Only `WebClient` is closed; `Vertx` remains open |
144+
145+
Always use try-with-resources to avoid leaking `Vertx` instances.
146+
147+
### Thread Safety
148+
149+
- **Client instances** are thread-safe — multiple threads can use the same client
150+
- **Builder instances** are NOT thread-safe — create separate builders per thread
151+
- All I/O operations execute on Vert.x event loop threads
152+
153+
### Performance Notes
154+
155+
Synchronous methods (`.get()`, `.post()`, `.delete()`) block the calling thread despite using Vert.x's async API internally. Vert.x still provides benefits at the network layer: non-blocking I/O, efficient connection pooling, and lower thread usage overall.
156+
157+
Async methods (`.getAsyncSSE()`, `.postAsyncSSE()`) are truly async — they return a `CompletableFuture` immediately.
158+
159+
### Troubleshooting
160+
161+
**Client not being used** — If logs show `JdkA2AHttpClient` instead of `VertxA2AHttpClient`, verify Vert.x WebClient is on the classpath:
162+
163+
```bash
164+
mvn dependency:tree | grep vertx-web-client
165+
```
166+
167+
**ClassNotFoundException for Vert.x** — Add the `vertx-web-client` dependency (see above). For Quarkus, ensure `quarkus-vertx` is present.
168+
169+
**Memory leaks** — Always use try-with-resources when creating `VertxA2AHttpClient` with the no-args constructor.
170+
171+
### Version Compatibility
172+
173+
- **Java**: 17+
174+
- **Vert.x**: 4.x (tested with 4.5.0+)
175+
- **Quarkus**: Any version using Vert.x 4.x
176+
- **Jakarta EE**: 9.0+
177+
178+
## Android HTTP Client
179+
180+
HTTP client implementation for Android applications.
181+
182+
```xml
183+
<dependency>
184+
<groupId>org.a2aproject.sdk</groupId>
185+
<artifactId>a2a-java-sdk-http-client-android</artifactId>
186+
</dependency>
187+
```

0 commit comments

Comments
 (0)