docs: add spring subscription example client

README.md

@@ -19,6 +19,10 @@ See [`docs/CODEBASE_OVERVIEW.md`](docs/CODEBASE_OVERVIEW.md) for details about r
 ## Examples
 Examples are located in the [`nostr-java-examples`](./nostr-java-examples) module.
 
+- [`SpringSubscriptionExample`](nostr-java-examples/src/main/java/nostr/examples/SpringSubscriptionExample.java)
+  shows how to open a non-blocking `NostrSpringWebSocketClient` subscription and close it after a
+  fixed duration.
+
 ## Streaming subscriptions
 
 The client and API layers expose a non-blocking streaming API for long-lived subscriptions. Use

docs/reference/nostr-java-api.md

@@ -129,7 +129,9 @@ public void close()
 `subscribe` opens a dedicated WebSocket per relay, returns immediately, and streams raw relay
 messages to the provided listener. The returned `AutoCloseable` sends a `CLOSE` command and releases
 resources when invoked. Because callbacks execute on the WebSocket thread, delegate heavy
-processing to another executor to avoid stalling inbound traffic.
+processing to another executor to avoid stalling inbound traffic. The
+[`SpringSubscriptionExample`](../../nostr-java-examples/src/main/java/nostr/examples/SpringSubscriptionExample.java)
+demonstrates how to open a subscription and close it after a fixed duration.
 
 ### Configuration
 - `RetryConfig` – enables Spring Retry support.

nostr-java-examples/src/main/java/nostr/examples/SpringSubscriptionExample.java

@@ -0,0 +1,47 @@
+package nostr.examples;
+
+import java.time.Duration;
+import java.util.Map;
+import nostr.api.NostrSpringWebSocketClient;
+import nostr.base.Kind;
+import nostr.event.filter.Filters;
+import nostr.event.filter.KindFilter;
+
+/**
+ * Example showing how to open a non-blocking subscription using {@link NostrSpringWebSocketClient}
+ * and close it after a fixed duration.
+ */
+public class SpringSubscriptionExample {
+
+  private static final Map<String, String> RELAYS = Map.of("local", "ws://localhost:5555");
+  private static final Duration LISTEN_DURATION = Duration.ofSeconds(30);
+
+  public static void main(String[] args) throws Exception {
+    NostrSpringWebSocketClient client = new NostrSpringWebSocketClient();
+    client.setRelays(RELAYS);
+
+    Filters filters = new Filters(new KindFilter<>(Kind.TEXT_NOTE));
+
+    AutoCloseable subscription =
+        client.subscribe(
+            filters,
+            "example-subscription",
+            message -> System.out.printf("Received from relay: %s%n", message),
+            error ->
+                System.err.printf(
+                    "Subscription error for %s: %s%n", RELAYS.keySet(), error.getMessage()));
+
+    try {
+      System.out.printf(
+          "Listening for %d seconds. Publish events to %s to see them here.%n",
+          LISTEN_DURATION.toSeconds(), RELAYS.values());
+      Thread.sleep(LISTEN_DURATION.toMillis());
+    } finally {
+      try {
+        subscription.close();
+      } finally {
+        client.close();
+      }
+    }
+  }
+}