Skip to content

Commit e69f97d

Browse files
committed
Improve javadoc
1 parent dd06c44 commit e69f97d

2 files changed

Lines changed: 237 additions & 7 deletions

File tree

‎transport/rest/src/main/java/io/a2a/transport/rest/context/RestContextKeys.java‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,20 @@
33
/**
44
* Shared REST context keys for A2A protocol data.
55
*
6-
* These keys provide access to REST context information,
7-
* enabling rich context access in service method implementations.
6+
* <p>These keys provide access to REST context information stored in
7+
* {@link io.a2a.server.ServerCallContext}, enabling rich context access
8+
* in service method implementations and middleware.
9+
*
10+
* <h2>Usage Example</h2>
11+
* <pre>{@code
12+
* public void processRequest(ServerCallContext context) {
13+
* String tenant = context.get(RestContextKeys.TENANT_KEY);
14+
* String method = context.get(RestContextKeys.METHOD_NAME_KEY);
15+
* Map<String, String> headers = context.get(RestContextKeys.HEADERS_KEY);
16+
* }
17+
* }</pre>
18+
*
19+
* @see io.a2a.server.ServerCallContext
820
*/
921
public final class RestContextKeys {
1022

‎transport/rest/src/main/java/io/a2a/transport/rest/handler/RestHandler.java‎

Lines changed: 223 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,41 @@
7373
* manages the lifecycle of agent interactions including message sending, task
7474
* management, and push notification configurations.
7575
*
76-
* <p>The handler supports both blocking and streaming operations, and validates
77-
* protocol versions and required extensions before processing requests.
76+
* <h2>Request Flow</h2>
77+
* <p>HTTP REST requests flow through this handler to the underlying {@link RequestHandler},
78+
* which coordinates with the agent executor and event queue system:
79+
* <pre>
80+
* HTTP Request → RestHandler → RequestHandler → AgentExecutor
81+
* ↓ ↓
82+
* Validation EventQueue → Response
83+
* </pre>
84+
*
85+
* <h2>Supported Operations</h2>
86+
* <ul>
87+
* <li>Message sending (blocking and streaming)</li>
88+
* <li>Task management (get, list, cancel, subscribe)</li>
89+
* <li>Push notification configurations (create, get, list, delete)</li>
90+
* <li>Agent card retrieval (public and extended)</li>
91+
* </ul>
92+
*
93+
* <h2>Error Handling</h2>
94+
* <p>All A2A protocol errors are caught and converted to appropriate HTTP status codes
95+
* via {@link #mapErrorToHttpStatus(A2AError)}. Protocol version and required extensions
96+
* are validated before processing requests.
97+
*
98+
* <h2>CDI Integration</h2>
99+
* <p>This handler is an {@code @ApplicationScoped} CDI bean that requires:
100+
* <ul>
101+
* <li>{@link AgentCard} qualified with {@code @PublicAgentCard}</li>
102+
* <li>{@link RequestHandler} for processing A2A operations</li>
103+
* <li>{@link Executor} qualified with {@code @Internal} for async operations</li>
104+
* <li>Optional {@link AgentCard} qualified with {@code @ExtendedAgentCard}</li>
105+
* </ul>
106+
*
107+
* @see RequestHandler
108+
* @see io.a2a.server.requesthandlers.DefaultRequestHandler
109+
* @see io.a2a.spec.AgentCard
110+
* @see ServerCallContext
78111
*/
79112
@ApplicationScoped
80113
public class RestHandler {
@@ -137,10 +170,45 @@ public RestHandler(AgentCard agentCard, RequestHandler requestHandler, Executor
137170
/**
138171
* Handles a blocking message send request.
139172
*
173+
* <p>This method processes an HTTP POST request containing a message to be sent to the agent.
174+
* The request is validated for protocol version and required extensions before being forwarded
175+
* to the {@link RequestHandler}. The method blocks until the agent produces a terminal event
176+
* or requires authentication/input.
177+
*
178+
* <p><b>Example Request:</b></p>
179+
* <pre>{@code
180+
* POST /v1/tenants/{tenant}/messages
181+
* Content-Type: application/json
182+
*
183+
* {
184+
* "message": {
185+
* "parts": [
186+
* {"text": "What is the weather in San Francisco?"}
187+
* ]
188+
* }
189+
* }
190+
* }</pre>
191+
*
192+
* <p><b>Example Response:</b></p>
193+
* <pre>{@code
194+
* HTTP/1.1 200 OK
195+
* Content-Type: application/json
196+
*
197+
* {
198+
* "task": {
199+
* "id": "task-123",
200+
* "status": {"state": "COMPLETED"},
201+
* "artifacts": [...]
202+
* }
203+
* }
204+
* }</pre>
205+
*
140206
* @param context the server call context containing authentication and metadata
141207
* @param tenant the tenant identifier
142-
* @param body the JSON request body
208+
* @param body the JSON request body containing the message to send
143209
* @return the HTTP response containing the task or message result
210+
* @see #sendStreamingMessage(ServerCallContext, String, String)
211+
* @see RequestHandler#onMessageSend(io.a2a.spec.MessageSendParams, ServerCallContext)
144212
*/
145213
public HTTPRestResponse sendMessage(ServerCallContext context, String tenant, String body) {
146214

@@ -162,10 +230,47 @@ public HTTPRestResponse sendMessage(ServerCallContext context, String tenant, St
162230
/**
163231
* Handles a streaming message send request.
164232
*
233+
* <p>This method processes an HTTP POST request for streaming responses from the agent.
234+
* The response is returned as Server-Sent Events (SSE) via {@link HTTPRestStreamingResponse},
235+
* allowing clients to receive task updates and artifacts as they are produced by the agent.
236+
*
237+
* <p>This method requires the agent card to have {@code capabilities.streaming = true}.
238+
*
239+
* <p><b>Example Request:</b></p>
240+
* <pre>{@code
241+
* POST /v1/tenants/{tenant}/messages/stream
242+
* Content-Type: application/json
243+
*
244+
* {
245+
* "message": {
246+
* "parts": [
247+
* {"text": "Generate a long story"}
248+
* ]
249+
* }
250+
* }
251+
* }</pre>
252+
*
253+
* <p><b>Example Streaming Response:</b></p>
254+
* <pre>{@code
255+
* HTTP/1.1 200 OK
256+
* Content-Type: text/event-stream
257+
*
258+
* data: {"taskStatusUpdate":{"task":{"id":"task-123","status":{"state":"WORKING"}}}}
259+
*
260+
* data: {"taskArtifactUpdate":{"taskId":"task-123","artifacts":[{"parts":[{"text":"Once upon"}]}]}}
261+
*
262+
* data: {"taskArtifactUpdate":{"taskId":"task-123","artifacts":[{"parts":[{"text":" a time..."}]}]}}
263+
*
264+
* data: {"taskStatusUpdate":{"task":{"id":"task-123","status":{"state":"COMPLETED"}}}}
265+
* }</pre>
266+
*
165267
* @param context the server call context containing authentication and metadata
166268
* @param tenant the tenant identifier
167-
* @param body the JSON request body
269+
* @param body the JSON request body containing the message to send
168270
* @return the streaming HTTP response containing a publisher of events
271+
* @see #sendMessage(ServerCallContext, String, String)
272+
* @see RequestHandler#onMessageSendStream(io.a2a.spec.MessageSendParams, ServerCallContext)
273+
* @see HTTPRestStreamingResponse
169274
*/
170275
public HTTPRestResponse sendStreamingMessage(ServerCallContext context, String tenant, String body) {
171276
try {
@@ -189,11 +294,23 @@ public HTTPRestResponse sendStreamingMessage(ServerCallContext context, String t
189294
/**
190295
* Handles a task cancellation request.
191296
*
297+
* <p>Attempts to cancel a running task identified by the task ID. The cancellation
298+
* request is forwarded to the {@link RequestHandler}, which signals the agent executor
299+
* to stop processing. The agent should transition the task to {@code CANCELED} state.
300+
*
301+
* <p><b>Example Request:</b></p>
302+
* <pre>{@code
303+
* POST /v1/tenants/{tenant}/tasks/{taskId}/cancel
304+
* }</pre>
305+
*
192306
* @param context the server call context containing authentication and metadata
193307
* @param tenant the tenant identifier
194308
* @param body the JSON request body
195309
* @param taskId the ID of the task to cancel
196310
* @return the HTTP response containing the cancelled task
311+
* @throws InvalidParamsError if taskId is null or empty
312+
* @see RequestHandler#onCancelTask(TaskIdParams, ServerCallContext)
313+
* @see io.a2a.server.agentexecution.AgentExecutor#cancel
197314
*/
198315
@SuppressWarnings("unchecked")
199316
public HTTPRestResponse cancelTask(ServerCallContext context, String tenant, String body, String taskId) {
@@ -244,10 +361,30 @@ public HTTPRestResponse createTaskPushNotificationConfiguration(ServerCallContex
244361
/**
245362
* Subscribes to task updates via a streaming connection.
246363
*
364+
* <p>Creates a Server-Sent Events (SSE) stream that delivers real-time updates for an
365+
* existing task. This allows clients to reconnect to ongoing or completed tasks and
366+
* receive their event history and future updates.
367+
*
368+
* <p>This method requires the agent card to have {@code capabilities.streaming = true}.
369+
*
370+
* <p><b>Example Request:</b></p>
371+
* <pre>{@code
372+
* GET /v1/tenants/{tenant}/tasks/{taskId}/subscribe
373+
* }</pre>
374+
*
375+
* <p><b>Use Cases:</b></p>
376+
* <ul>
377+
* <li>Reconnecting to a task after network interruption</li>
378+
* <li>Monitoring long-running tasks from multiple clients</li>
379+
* <li>Viewing historical events for completed tasks</li>
380+
* </ul>
381+
*
247382
* @param context the server call context containing authentication and metadata
248383
* @param tenant the tenant identifier
249384
* @param taskId the ID of the task to subscribe to
250385
* @return the streaming HTTP response containing task updates
386+
* @see RequestHandler#onSubscribeToTask(TaskIdParams, ServerCallContext)
387+
* @see #sendStreamingMessage(ServerCallContext, String, String)
251388
*/
252389
public HTTPRestResponse subscribeToTask(ServerCallContext context, String tenant, String taskId) {
253390
try {
@@ -291,16 +428,39 @@ public HTTPRestResponse getTask(ServerCallContext context, String tenant, String
291428
/**
292429
* Lists tasks with optional filtering and pagination.
293430
*
431+
* <p>Retrieves a list of tasks with support for filtering by context, status, and timestamp,
432+
* along with pagination controls. This method is useful for task management dashboards,
433+
* monitoring systems, and task history retrieval.
434+
*
435+
* <p><b>Example Request:</b></p>
436+
* <pre>{@code
437+
* GET /v1/tenants/{tenant}/tasks?status=COMPLETED&pageSize=10&includeArtifacts=true
438+
* }</pre>
439+
*
440+
* <p><b>Query Parameters:</b></p>
441+
* <ul>
442+
* <li>{@code contextId} - Filter tasks by conversation context</li>
443+
* <li>{@code status} - Filter by task state (SUBMITTED, WORKING, COMPLETED, etc.)</li>
444+
* <li>{@code pageSize} - Maximum tasks to return (for pagination)</li>
445+
* <li>{@code pageToken} - Token for retrieving next page of results</li>
446+
* <li>{@code historyLength} - Maximum history entries to include per task</li>
447+
* <li>{@code statusTimestampAfter} - ISO-8601 timestamp for filtering recent tasks</li>
448+
* <li>{@code includeArtifacts} - Whether to include task artifacts in response</li>
449+
* </ul>
450+
*
294451
* @param context the server call context containing authentication and metadata
295452
* @param tenant the tenant identifier
296453
* @param contextId optional context ID to filter by
297-
* @param status optional task status to filter by
454+
* @param status optional task status to filter by (must be valid {@link TaskState} value)
298455
* @param pageSize optional maximum number of tasks to return
299456
* @param pageToken optional token for pagination
300457
* @param historyLength optional maximum number of history entries per task
301458
* @param statusTimestampAfter optional ISO-8601 timestamp to filter tasks updated after
302459
* @param includeArtifacts optional flag to include task artifacts
303460
* @return the HTTP response containing the list of tasks
461+
* @throws InvalidParamsError if status is not a valid TaskState or timestamp is malformed
462+
* @see RequestHandler#onListTasks(ListTasksParams, ServerCallContext)
463+
* @see TaskState
304464
*/
305465
public HTTPRestResponse listTasks(ServerCallContext context, String tenant,
306466
@Nullable String contextId, @Nullable String status,
@@ -552,6 +712,24 @@ public void onComplete() {
552712
});
553713
}
554714

715+
/**
716+
* Maps A2A protocol errors to HTTP status codes.
717+
*
718+
* <p>This method ensures consistent HTTP status code mapping for all A2A errors:
719+
* <ul>
720+
* <li>400 - Invalid request, JSON parse errors, missing extensions</li>
721+
* <li>404 - Method not found, task not found</li>
722+
* <li>409 - Task not cancelable (conflict)</li>
723+
* <li>415 - Unsupported content type</li>
724+
* <li>422 - Invalid parameters (unprocessable entity)</li>
725+
* <li>500 - Internal errors</li>
726+
* <li>501 - Not implemented (unsupported operations, version)</li>
727+
* <li>502 - Bad gateway (invalid agent response)</li>
728+
* </ul>
729+
*
730+
* @param error the A2A error to map
731+
* @return the corresponding HTTP status code
732+
*/
555733
private int mapErrorToHttpStatus(A2AError error) {
556734
if (error instanceof InvalidRequestError || error instanceof JSONParseError) {
557735
return 400;
@@ -589,9 +767,22 @@ private int mapErrorToHttpStatus(A2AError error) {
589767
/**
590768
* Retrieves the extended agent card if configured.
591769
*
770+
* <p>The extended agent card provides additional metadata beyond the public agent card,
771+
* such as tenant-specific configurations or private capabilities. This endpoint requires
772+
* the agent card to have {@code capabilities.extendedAgentCard = true} and a CDI-produced
773+
* {@code @ExtendedAgentCard} instance.
774+
*
775+
* <p><b>Example Request:</b></p>
776+
* <pre>{@code
777+
* GET /v1/tenants/{tenant}/extended-agent-card
778+
* }</pre>
779+
*
592780
* @param context the server call context containing authentication and metadata
593781
* @param tenant the tenant identifier
594782
* @return the HTTP response containing the extended agent card
783+
* @throws ExtendedAgentCardNotConfiguredError if extended agent card is not available
784+
* @see #getAgentCard()
785+
* @see AgentCard
595786
*/
596787
public HTTPRestResponse getExtendedAgentCard(ServerCallContext context, String tenant) {
597788
try {
@@ -609,7 +800,34 @@ public HTTPRestResponse getExtendedAgentCard(ServerCallContext context, String t
609800
/**
610801
* Retrieves the public agent card.
611802
*
803+
* <p>The agent card is a self-describing manifest that provides essential metadata about
804+
* the agent, including its capabilities, supported skills, communication methods, and
805+
* security requirements. This is the primary discovery endpoint for clients to understand
806+
* what the agent can do and how to interact with it.
807+
*
808+
* <p><b>Example Request:</b></p>
809+
* <pre>{@code
810+
* GET /v1/agent-card
811+
* }</pre>
812+
*
813+
* <p><b>Example Response:</b></p>
814+
* <pre>{@code
815+
* {
816+
* "name": "Weather Agent",
817+
* "description": "Provides weather information",
818+
* "version": "1.0.0",
819+
* "capabilities": {
820+
* "streaming": true,
821+
* "pushNotifications": false
822+
* },
823+
* "skills": [...],
824+
* "supportedInterfaces": [...]
825+
* }
826+
* }</pre>
827+
*
612828
* @return the HTTP response containing the agent card
829+
* @see AgentCard
830+
* @see #getExtendedAgentCard(ServerCallContext, String)
613831
*/
614832
public HTTPRestResponse getAgentCard() {
615833
try {

0 commit comments

Comments
 (0)