WebSocket API: document public API

jknack · jknack · commit ec9f4c50fa71 · 2019-09-25T11:14:21.000-03:00
diff --git a/examples/src/main/java/examples/WebSocketApp.java b/examples/src/main/java/examples/WebSocketApp.java
@@ -2,6 +2,7 @@
 
 import io.jooby.ExecutionMode;
 import io.jooby.Jooby;
+import io.jooby.WebSocketCloseStatus;
 
 import java.nio.file.Paths;
 import java.util.concurrent.Executors;
@@ -16,6 +17,7 @@ public class WebSocketApp extends Jooby {
     ws("/ws", (ctx, initializer) -> {
       initializer.onConnect(ws -> {
         ws.send("Welcome");
+        ws.close();
       });
       initializer.onMessage((ws, msg) -> {
         ws.send("Got: " + msg.value(), true);
diff --git a/examples/www/websocket/index.js b/examples/www/websocket/index.js
@@ -27,7 +27,8 @@ function connect() {
   };
 
   webSocket.onclose = function (event) {
-    updateOutput("Connection Closed");
+    console.log(event)
+    updateOutput("Connection Closed: " + event.code + "(" + event.reason + ")");
     connectBtn.disabled = false;
     sendBtn.disabled = true;
   };
diff --git a/jooby/src/main/java/io/jooby/Context.java b/jooby/src/main/java/io/jooby/Context.java
@@ -1065,10 +1065,32 @@ public interface Context extends Registry {
    * Factory methods
    * **********************************************************************************************
    */
+
+  /**
+   * Wrap a HTTP context and make read only. Attempt to modify the HTTP response resulted in
+   * exception.
+   *
+   * @param ctx Originating context.
+   * @return Read only context.
+   */
   static @Nonnull Context readOnly(@Nonnull Context ctx) {
     return new ReadOnlyContext(ctx);
   }
 
+  /**
+   * Wrap a HTTP context and make it WebSocket friendly. Attempt to modify the HTTP response
+   * is completely ignored, except for {@link #send(byte[])} and {@link #send(String)} which
+   * are delegated to the given web socket.
+   *
+   * This context is necessary for creating a bridge between {@link MessageEncoder}
+   * and {@link WebSocket}.
+   *
+   * This method is part of Public API, but direct usage is discourage.
+   *
+   * @param ctx Originating context.
+   * @param ws WebSocket.
+   * @return Read only context.
+   */
   static @Nonnull Context websocket(@Nonnull Context ctx, @Nonnull WebSocket ws) {
     return new WebSocketSender(ctx, ws);
   }
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.Initializer handler) {
+  @Nonnull @Override public Route ws(@Nonnull String pattern, @Nonnull WebSocket.Initializer handler) {
     return router.ws(pattern, handler);
   }
 
diff --git a/jooby/src/main/java/io/jooby/StatusCode.java b/jooby/src/main/java/io/jooby/StatusCode.java
@@ -17,7 +17,7 @@
  * @see <a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes">List of HTTP status codes -
  *      Wikipedia</a>
  */
-public class StatusCode {
+public final class StatusCode {
 
   // 1xx Informational
 
diff --git a/jooby/src/main/java/io/jooby/Value.java b/jooby/src/main/java/io/jooby/Value.java
@@ -4,11 +4,9 @@
 import io.jooby.internal.HashValue;
 import io.jooby.internal.MissingValue;
 import io.jooby.internal.SingleValue;
-import io.jooby.internal.reflect.$Types;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
-import java.lang.reflect.Type;
 import java.time.Instant;
 import java.time.LocalDateTime;
 import java.time.ZoneOffset;
diff --git a/jooby/src/main/java/io/jooby/WebSocket.java b/jooby/src/main/java/io/jooby/WebSocket.java
@@ -28,6 +28,8 @@
  *
  * }</pre>
  *
+ * NOTE: Websocket API ONLY handles text messages (not binary message).
+ *
  * @author edgar
  * @since 2.2.0
  */
@@ -72,15 +74,43 @@ interface OnMessage {
     void onMessage(@Nonnull WebSocket ws, @Nonnull WebSocketMessage message);
   }
 
+  /**
+   * On close callback. Generated when client close the connection or when explicit calls to
+   * {@link #close(WebSocketCloseStatus)} or {@link #disconnect()}.
+   */
   interface OnClose {
-    void onClose(WebSocket ws, WebSocketCloseStatus closeStatus);
+    /**
+     * Generated when client close the connection or when explicit calls to
+     * {@link #close(WebSocketCloseStatus)} or {@link #disconnect()}.
+     *
+     * @param ws WebSocket.
+     * @param closeStatus Close status.
+     */
+    void onClose(@Nonnull WebSocket ws, @Nonnull WebSocketCloseStatus closeStatus);
   }
 
+  /**
+   * On error callback. Generated when unexpected error occurs.
+   */
   interface OnError {
-    void onError(WebSocket ws, Throwable cause);
+    /**
+     * Error callback, let you listen for exception. Websocket might or might not be open.
+     *
+     * @param ws Websocket.
+     * @param cause Cause.
+     */
+    void onError(@Nonnull WebSocket ws, @Nonnull Throwable cause);
   }
 
-  Context getContext();
+  /**
+   * Originating HTTP context. Please note this is a read-only context, so you are not allowed
+   * to modify or produces a response from it.
+   *
+   * The context let give you access to originating request (then one that was upgrade it).
+   *
+   * @return Read-only originating HTTP request.
+   */
+  @Nonnull Context getContext();
 
   /**
    * Context attributes (a.k.a request attributes).
@@ -115,22 +145,84 @@ interface OnError {
     return this;
   }
 
-  default WebSocket send(String message) {
+  /**
+   * Send a text message to client.
+   *
+   * @param message Text Message.
+   * @return This websocket.
+   */
+  default @Nonnull WebSocket send(@Nonnull String message) {
     return send(message, false);
   }
 
-  WebSocket send(String message, boolean broadcast);
+  /**
+   * Send a text message to current client (broadcast = false) or to ALL connected clients under the
+   * websocket path (broadcast = true).
+   *
+   * @param message Text Message.
+   * @param broadcast True to send to all connected clients.
+   * @return This websocket.
+   */
+  @Nonnull WebSocket send(@Nonnull String message, boolean broadcast);
 
-  default WebSocket send(byte[] bytes) {
-    return send(bytes, false);
+  /**
+   * Send a text message to client.
+   *
+   * @param message Text Message.
+   * @return This websocket.
+   */
+  default @Nonnull WebSocket send(@Nonnull byte[] message) {
+    return send(message, false);
   }
 
-  WebSocket send(byte[] bytes, boolean broadcast);
+  /**
+   * Send a text message to current client (broadcast = false) or to ALL connected clients under the
+   * websocket path (broadcast = true).
+   *
+   * @param message Text Message.
+   * @param broadcast True to send to all connected clients.
+   * @return This websocket.
+   */
+  @Nonnull WebSocket send(@Nonnull byte[] message, boolean broadcast);
 
-  default WebSocket render(Object message) {
-    return render(message, false);
+  /**
+   * Encode a value and send a text message to client.
+   *
+   * @param value Value to send.
+   * @return This websocket.
+   */
+  default @Nonnull WebSocket render(@Nonnull Object value) {
+    return render(value, false);
   }
 
-  WebSocket render(Object message, boolean broadcast);
+  /**
+   * Encode a value and send a text message to current client (broadcast = false) or to ALL
+   * connected clients under the websocket path (broadcast = true).
+   *
+   * @param value Value to send.
+   * @param broadcast True to send to all connected clients.
+   * @return This websocket.
+   */
+  @Nonnull WebSocket render(@Nonnull Object value, boolean broadcast);
+
+  /**
+   * Close the web socket and send a {@link WebSocketCloseStatus#NORMAL} code to client.
+   *
+   * This method fires a {@link OnClose#onClose(WebSocket, WebSocketCloseStatus)} callback.
+   *
+   * @return This websocket.
+   */
+  default @Nonnull WebSocket close() {
+    return close(WebSocketCloseStatus.NORMAL);
+  }
 
+  /**
+   * Close the web socket and send a close status code to client.
+   *
+   * This method fires a {@link OnClose#onClose(WebSocket, WebSocketCloseStatus)} callback.
+   *
+   * @param closeStatus Close status.
+   * @return This websocket.
+   */
+  @Nonnull WebSocket close(@Nonnull WebSocketCloseStatus closeStatus);
 }
diff --git a/jooby/src/main/java/io/jooby/WebSocketCloseStatus.java b/jooby/src/main/java/io/jooby/WebSocketCloseStatus.java
@@ -1,7 +1,15 @@
 package io.jooby;
 
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import java.util.Optional;
 
+/**
+ * Collection of websocket close status.
+ *
+ * @author edgar
+ * @since 2.2.0
+ */
 public class WebSocketCloseStatus {
 
   /**
@@ -181,19 +189,41 @@ public class WebSocketCloseStatus {
 
   private String reason;
 
-  public WebSocketCloseStatus(int code, String reason) {
+  /**
+   * Creates a new websocket close status.
+   *
+   * @param code Status code.
+   * @param reason Reason.
+   */
+  public WebSocketCloseStatus(int code, @Nonnull String reason) {
     this.code = code;
     this.reason = reason;
   }
 
+  /**
+   * Status code.
+   *
+   * @return Status code.
+   */
   public int getCode() {
     return code;
   }
 
-  public String getReason() {
+  /**
+   * Reason or <code>null</code>.
+   *
+   * @return Reason or <code>null</code>.
+   */
+  public @Nullable String getReason() {
     return reason;
   }
 
+  /**
+   * Map the status code to one of the existing web socket status.
+   *
+   * @param code Status code.
+   * @return Web socket status or empty.
+   */
   public static Optional<WebSocketCloseStatus> valueOf(int code) {
     switch (code) {
       case -1:
diff --git a/jooby/src/main/java/io/jooby/WebSocketConfigurer.java b/jooby/src/main/java/io/jooby/WebSocketConfigurer.java
@@ -1,12 +1,44 @@
 package io.jooby;
 
+import javax.annotation.Nonnull;
+
+/**
+ * Websocket configurer. Allow to register callbacks for websocket.
+ *
+ * @author edgar
+ * @since  2.2.0
+ */
 public interface WebSocketConfigurer {
 
-  WebSocketConfigurer onConnect(WebSocket.OnConnect callback);
+  /**
+   * Register an <code>onConnect</code> callback.
+   *
+   * @param callback Callback.
+   * @return This configurer.
+   */
+  @Nonnull WebSocketConfigurer onConnect(@Nonnull WebSocket.OnConnect callback);
 
-  WebSocketConfigurer onMessage(WebSocket.OnMessage callback);
+  /**
+   * Register an <code>onMessage</code> callback.
+   *
+   * @param callback Callback.
+   * @return This configurer.
+   */
+  @Nonnull WebSocketConfigurer onMessage(@Nonnull WebSocket.OnMessage callback);
 
-  WebSocketConfigurer onError(WebSocket.OnError callback);
+  /**
+   * Register an <code>onError</code> callback.
+   *
+   * @param callback Callback.
+   * @return This configurer.
+   */
+  @Nonnull WebSocketConfigurer onError(@Nonnull WebSocket.OnError callback);
 
-  WebSocketConfigurer onClose(WebSocket.OnClose callback);
+  /**
+   * Register an <code>onClose</code> callback.
+   *
+   * @param callback Callback.
+   * @return This configurer.
+   */
+  @Nonnull WebSocketConfigurer onClose(@Nonnull WebSocket.OnClose callback);
 }
diff --git a/jooby/src/main/java/io/jooby/WebSocketMessage.java b/jooby/src/main/java/io/jooby/WebSocketMessage.java
@@ -5,6 +5,12 @@
 import javax.annotation.Nonnull;
 import java.lang.reflect.Type;
 
+/**
+ * Websocket message generated from a {@link WebSocket.OnMessage} callback. Message is a subclass.
+ *
+ * @author edgar
+ * @since 2.2.0
+ */
 public interface WebSocketMessage extends Value {
   /**
    * Convert this value to the given type. Support values are single-value, array-value and
@@ -16,7 +22,14 @@ public interface WebSocketMessage extends Value {
    */
   @Nonnull <T> T to(@Nonnull Type type);
 
-  static WebSocketMessage create(Context ctx, byte[] bytes) {
+  /**
+   * Creates a websocket message.
+   *
+   * @param ctx HTTP context.
+   * @param bytes Text message as byte array.
+   * @return A websocket message.
+   */
+  static @Nonnull WebSocketMessage create(@Nonnull Context ctx, @Nonnull byte[] bytes) {
     return new WebSocketMessageImpl(ctx, bytes);
   }
 }
diff --git a/modules/jooby-netty/src/main/java/io/jooby/internal/netty/NettyWebSocket.java b/modules/jooby-netty/src/main/java/io/jooby/internal/netty/NettyWebSocket.java

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.Initializer handler) {`
	`295`	`+ @Nonnull @Override public Route ws(@Nonnull String pattern, @Nonnull WebSocket.Initializer handler) {`
`296`	`296`	`return router.ws(pattern, handler);`
`297`	`297`	`}`
`298`	`298`