WebSocket: the two clean styles — self-describing WebsocketHandler + @Websocket/@OnX

README.md

@@ -24,3 +24,12 @@ GET /services/java/sample-java-websocket-decorator/demo/websocket/WebsocketStatu
 ```
 
 Returns `{"registered": true}` when the `"java-chat"` endpoint is active.
+
+## Websocket styles
+
+Two ways to write a Java WebSocket handler — pick one per `@Component` class (never both), like Spring:
+
+- **Strong interface** — `ChatHandler` is a `@Component` that implements `WebsocketHandler` and supplies its own `endpoint()` (like `TextWebSocketHandler`); no `@Websocket` annotation.
+- **Method-level annotations** — `TickerHandler` is a `@Websocket(endpoint = …)` class with `@OnOpen`/`@OnMessage`/`@OnClose` methods (Jakarta `@ServerEndpoint` style — the endpoint has no method-level home).
+
+See the [Develop guide](https://www.dirigible.io/help/develop/websockets/) and the [Java SDK](https://www.dirigible.io/sdk/).

sample-java-websocket-decorator/demo/websocket/ChatHandler.java

@@ -1,35 +1,41 @@
 package demo.websocket;
 
-import org.eclipse.dirigible.sdk.net.Websocket;
+import org.eclipse.dirigible.sdk.component.Component;
+import org.eclipse.dirigible.sdk.net.WebsocketHandler;
 
 /**
- * Demonstrates {@code @Websocket}: registers this class as the handler for the
- * {@code "java-chat"} WebSocket endpoint. Clients connect via
- * {@code ws://<host>/websockets/stomp/java-chat}.
- *
- * <p>
- * All four lifecycle methods are shown; any subset is valid — missing methods are silently skipped
- * by the runtime.
+ * Strong-interface websocket style: a {@code @Component} that implements {@link WebsocketHandler}
+ * and supplies its own endpoint — no {@code @Websocket} annotation. Clients connect via
+ * {@code ws://<host>/websockets/stomp/java-chat}. Override only the callbacks you need; the rest
+ * inherit the no-op default.
  */
-@Websocket(name = "Java Chat", endpoint = "java-chat")
-public class ChatHandler {
+@Component
+public class ChatHandler implements WebsocketHandler {
 
     static final String ENDPOINT = "java-chat";
 
+    @Override
+    public String endpoint() {
+        return ENDPOINT;
+    }
+
+    @Override
     public void onOpen() {
         System.out.println("ChatHandler: client connected");
     }
 
+    @Override
     public void onMessage(String message, String from) {
         System.out.println("ChatHandler: " + from + " says: " + message);
     }
 
+    @Override
     public void onError(String error) {
         System.out.println("ChatHandler: error: " + error);
     }
 
+    @Override
     public void onClose() {
         System.out.println("ChatHandler: client disconnected");
     }
-
 }

sample-java-websocket-decorator/demo/websocket/TickerHandler.java

@@ -0,0 +1,29 @@
+package demo.websocket;
+
+import org.eclipse.dirigible.sdk.net.OnClose;
+import org.eclipse.dirigible.sdk.net.OnMessage;
+import org.eclipse.dirigible.sdk.net.OnOpen;
+import org.eclipse.dirigible.sdk.net.Websocket;
+
+/**
+ * Method-level callback style (Jakarta-WebSocket flavour): annotate methods with @OnOpen / @OnMessage /
+ * @OnClose. A non-void @OnMessage return value is sent back to the client.
+ */
+@Websocket(name = "Java Ticker", endpoint = "java-ticker")
+public class TickerHandler {
+
+    @OnOpen
+    public void opened() {
+        System.out.println("TickerHandler: client connected");
+    }
+
+    @OnMessage
+    public String message(String message, String from) {
+        return "tick: " + message;
+    }
+
+    @OnClose
+    public void closed() {
+        System.out.println("TickerHandler: client disconnected");
+    }
+}