fix(java-client): configurable event queue, keep events on overflow, cancel on interrupt, typed diagnostics

- eventQueueCapacity option (default 1024, was hard-coded 16)
- overflow retains buffered events and delivers the error after them
- interrupt cancels the gRPC call and restores the interrupt flag
- ping/getSessionState/getWorkerInfo/drainEvents on MxGatewaySession

clients/java/README.md

@@ -79,6 +79,30 @@ only stops the client from waiting; it does not abort an in-flight MXAccess COM
 call on the worker STA. It is a **single-consumer** surface: drive
 `hasNext()`/`next()` (or `nextItem()`) from one thread only.
 
+### Event buffer, overflow, and interrupts
+
+The iterator buffers events in a bounded queue whose size is
+`MxGatewayClientOptions.builder().eventQueueCapacity(n)` (default 1024; it was a
+hard-coded 16, which a short burst could overflow). If the consumer falls more
+than `n` events behind, the client cancels the call, keeps the events already
+buffered, and throws `MxGatewayException` only after you have drained them. Resume
+with `streamEventsAfter(lastSeenWorkerSequence)`. If the consuming thread is
+interrupted, the call is cancelled, the interrupt flag is restored, and the
+iterator throws a `CANCELLED` `StatusRuntimeException`.
+
+`streamEventsAsync(request, StreamObserver<MxEvent>)` is the non-dropping
+alternative: it delivers each event to your observer on the gRPC thread with no
+client-side queue, so nothing is discarded by the client (a slow observer
+instead applies normal gRPC flow control).
+
+### Session diagnostics
+
+`MxGatewaySession` exposes typed helpers for the worker diagnostic commands:
+`ping(message)` (returns the raw `MxCommandReply`), `getSessionState()`
+(`SessionState`), `getWorkerInfo()` (`WorkerInfoReply`: process id, version,
+ProgID, CLSID) and `drainEvents(maxEvents)` (`List<MxEvent>`; replies are
+bounded server-side, so loop until an empty list).
+
 ### Reconnect-replay gap signal
 
 When you resume a stream with `streamEventsAfter(afterWorkerSequence)` and the