WebSocket API: document public API

jknack · jknack · commit 55d3923355a1 · 2019-09-25T09:33:33.000-03:00
diff --git a/jooby/src/main/java/io/jooby/Context.java b/jooby/src/main/java/io/jooby/Context.java
@@ -666,7 +666,7 @@ public interface Context extends Registry {
    */
   @Nonnull Context detach(@Nonnull Route.Handler next) throws Exception;
 
-  default @Nonnull Context upgrade(@Nonnull WebSocket.Handler handler) {
+  default @Nonnull Context upgrade(@Nonnull WebSocket.Initializer handler) {
     return null;
   }
 
diff --git a/jooby/src/main/java/io/jooby/Jooby.java b/jooby/src/main/java/io/jooby/Jooby.java
@@ -292,7 +292,7 @@ public <T> Jooby mvc(@Nonnull Class<T> router, @Nonnull Provider<T> provider) {
     }
   }
 
-  public Route ws(String pattern, WebSocket.Handler handler) {
+  public Route ws(String pattern, WebSocket.Initializer handler) {
     return router.ws(pattern, handler);
   }
 
diff --git a/jooby/src/main/java/io/jooby/Router.java b/jooby/src/main/java/io/jooby/Router.java
@@ -216,7 +216,14 @@ interface Match {
    */
   @Nonnull Router mvc(@Nonnull Object router);
 
-  @Nonnull Route ws(@Nonnull String pattern, @Nonnull WebSocket.Handler handler);
+  /**
+   * Add a websocket handler.
+   *
+   * @param pattern WebSocket path pattern.
+   * @param handler WebSocket handler.
+   * @return This route.
+   */
+  @Nonnull Route ws(@Nonnull String pattern, @Nonnull WebSocket.Initializer handler);
 
   /**
    * Returns all routes.
diff --git a/jooby/src/main/java/io/jooby/WebSocket.java b/jooby/src/main/java/io/jooby/WebSocket.java
@@ -3,17 +3,73 @@
 import javax.annotation.Nonnull;
 import java.util.Map;
 
+/**
+ * Websocket. Usage:
+ *
+ * <pre>{@code
+ *
+ *     ws("/pattern", (ctx, configurer) -> {
+ *       configurer.onConnect(ws -> {
+ *         // Connect callback
+ *       }):
+ *
+ *       configurer.onMessage((ws, message) -> {
+ *         ws.send("Got: " + message.value());
+ *       });
+ *
+ *       configurer.onClose((ws, closeStatus) -> {
+ *         // Closing websocket
+ *       });
+ *
+ *       configurer.onError((ws, cause) -> {
+ *
+ *       });
+ *     });
+ *
+ * }</pre>
+ *
+ * @author edgar
+ * @since 2.2.0
+ */
 public interface WebSocket {
-  interface Handler {
-    void init(Context ctx, WebSocketConfigurer configurer);
+  /**
+   * Websocket initializer. Give you access to a read-only {@link Context} you are free to access
+   * to request attributes, while attempt to modify a response results in exception.
+   */
+  interface Initializer {
+    /**
+     * Callback with a readonly context and websocket configurer.
+     *
+     * @param ctx Readonly context.
+     * @param configurer WebSocket configurer.
+     */
+    void init(@Nonnull Context ctx, @Nonnull WebSocketConfigurer configurer);
   }
 
+  /**
+   * On connect callback.
+   */
   interface OnConnect {
-    void onConnect(WebSocket ws);
+    /**
+     * On connect callback with recently created web socket.
+     *
+     * @param ws WebSocket.
+     */
+    void onConnect(@Nonnull WebSocket ws);
   }
 
+  /**
+   * On message callback. When a Message is send by a client, this callback allow you to
+   * handle/react to it.
+   */
   interface OnMessage {
-    void onMessage(WebSocket ws, WebSocketMessage message);
+    /**
+     * Generated when a client send a message.
+     *
+     * @param ws WebSocket.
+     * @param message Client message.
+     */
+    void onMessage(@Nonnull WebSocket ws, @Nonnull WebSocketMessage message);
   }
 
   interface OnClose {
diff --git a/jooby/src/main/java/io/jooby/internal/RouterImpl.java b/jooby/src/main/java/io/jooby/internal/RouterImpl.java
@@ -334,7 +334,7 @@ public Router encoder(@Nonnull MediaType contentType, @Nonnull MessageEncoder en
     return beanConverters;
   }
 
-  @Nonnull @Override public Route ws(@Nonnull String pattern, @Nonnull WebSocket.Handler handler) {
+  @Nonnull @Override public Route ws(@Nonnull String pattern, @Nonnull WebSocket.Initializer handler) {
     return route(GET, pattern, new WebSocketHandler(handler));
   }
 
diff --git a/jooby/src/main/java/io/jooby/internal/handler/WebSocketHandler.java b/jooby/src/main/java/io/jooby/internal/handler/WebSocketHandler.java
@@ -8,9 +8,9 @@
 import javax.annotation.Nonnull;
 
 public class WebSocketHandler implements Route.Handler {
-  private WebSocket.Handler handler;
+  private WebSocket.Initializer handler;
 
-  public WebSocketHandler(WebSocket.Handler handler) {
+  public WebSocketHandler(WebSocket.Initializer handler) {
     this.handler = handler;
   }
 
diff --git a/modules/jooby-netty/src/main/java/io/jooby/internal/netty/NettyContext.java b/modules/jooby-netty/src/main/java/io/jooby/internal/netty/NettyContext.java
@@ -267,7 +267,7 @@ public NettyContext(ChannelHandlerContext ctx, HttpRequest req, Router router, S
     return this.cookies;
   }
 
-  @Nonnull @Override public Context upgrade(WebSocket.Handler handler) {
+  @Nonnull @Override public Context upgrade(WebSocket.Initializer handler) {
     try {
       String webSocketURL = getProtocol() + "://" + req.headers().get(HttpHeaderNames.HOST) + path;
       WebSocketDecoderConfig config = WebSocketDecoderConfig.newBuilder()

Original file line number	Diff line number	Diff line change
`@@ -666,7 +666,7 @@ public interface Context extends Registry {`
`666`	`666`	`*/`
`667`	`667`	`@Nonnull Context detach(@Nonnull Route.Handler next) throws Exception;`
`668`	`668`
`669`		`- default @Nonnull Context upgrade(@Nonnull WebSocket.Handler handler) {`
	`669`	`+ default @Nonnull Context upgrade(@Nonnull WebSocket.Initializer handler) {`
`670`	`670`	`return null;`
`671`	`671`	`}`
`672`	`672`
Original file line number	Diff line number	Diff line change
`@@ -292,7 +292,7 @@ public <T> Jooby mvc(@Nonnull Class<T> router, @Nonnull Provider<T> provider) {`
`292`	`292`	`}`
`293`	`293`	`}`
`294`	`294`
`295`		`- public Route ws(String pattern, WebSocket.Handler handler) {`
	`295`	`+ public Route ws(String pattern, WebSocket.Initializer handler) {`
`296`	`296`	`return router.ws(pattern, handler);`
`297`	`297`	`}`
`298`	`298`
Original file line number	Diff line number	Diff line change
`@@ -334,7 +334,7 @@ public Router encoder(@Nonnull MediaType contentType, @Nonnull MessageEncoder en`
`334`	`334`	`return beanConverters;`
`335`	`335`	`}`
`336`	`336`
`337`		`- @Nonnull @Override public Route ws(@Nonnull String pattern, @Nonnull WebSocket.Handler handler) {`
	`337`	`+ @Nonnull @Override public Route ws(@Nonnull String pattern, @Nonnull WebSocket.Initializer handler) {`
`338`	`338`	`return route(GET, pattern, new WebSocketHandler(handler));`
`339`	`339`	`}`
`340`	`340`
Original file line number	Diff line number	Diff line change
`@@ -8,9 +8,9 @@`
`8`	`8`	`import javax.annotation.Nonnull;`
`9`	`9`
`10`	`10`	`public class WebSocketHandler implements Route.Handler {`
`11`		`- private WebSocket.Handler handler;`
	`11`	`+ private WebSocket.Initializer handler;`
`12`	`12`
`13`		`- public WebSocketHandler(WebSocket.Handler handler) {`
	`13`	`+ public WebSocketHandler(WebSocket.Initializer handler) {`
`14`	`14`	`this.handler = handler;`
`15`	`15`	`}`
`16`	`16`
Original file line number	Diff line number	Diff line change
`@@ -267,7 +267,7 @@ public NettyContext(ChannelHandlerContext ctx, HttpRequest req, Router router, S`
`267`	`267`	`return this.cookies;`
`268`	`268`	`}`
`269`	`269`
`270`		`- @Nonnull @Override public Context upgrade(WebSocket.Handler handler) {`
	`270`	`+ @Nonnull @Override public Context upgrade(WebSocket.Initializer handler) {`
`271`	`271`	`try {`
`272`	`272`	`String webSocketURL = getProtocol() + "://" + req.headers().get(HttpHeaderNames.HOST) + path;`
`273`	`273`	`WebSocketDecoderConfig config = WebSocketDecoderConfig.newBuilder()`