From 853905a7c03bb740882667b026e318343ea89343 Mon Sep 17 00:00:00 2001 From: Joakim Erdfelt Date: Fri, 22 Jun 2012 06:32:21 -0700 Subject: [PATCH] Collaborating with Jesse on WebSocket API --- .../eclipse/jetty/websocket/WebSocket.java | 258 +++++------------- .../jetty/websocket/api/WebSocket.java | 65 ++++- 2 files changed, 126 insertions(+), 197 deletions(-) diff --git a/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/WebSocket.java b/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/WebSocket.java index 12935192e0f..afffd22f7c6 100644 --- a/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/WebSocket.java +++ b/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/WebSocket.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2011 Intalio, Inc. + * Copyright (c) 2011 Mort Bay Consulting Pty. Ltd. * ====================================================================== * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 @@ -13,23 +13,13 @@ * * You may elect to redistribute this code under either of these licenses. *******************************************************************************/ -// ======================================================================== -// Copyright (c) 2010 Mort Bay Consulting Pty. Ltd. -// ------------------------------------------------------------------------ -// All rights reserved. This program and the accompanying materials -// are made available under the terms of the Eclipse Public License v1.0 -// and Apache License v2.0 which accompanies this distribution. -// The Eclipse Public License is available at -// http://www.eclipse.org/legal/epl-v10.html -// The Apache License v2.0 is available at -// http://www.opensource.org/licenses/apache2.0.php -// You may elect to redistribute this code under either of these licenses. -// ======================================================================== package org.eclipse.jetty.websocket; import java.io.IOException; +import org.eclipse.jetty.websocket.api.WebSocketPolicy; + /** * WebSocket Interface. *

@@ -37,31 +27,50 @@ import java.io.IOException; * The Interface has several nested interfaces, for each type of message that may be received. */ public interface WebSocket -{ +{ /** - * Called when a new websocket connection is accepted. - * @param connection The Connection object to use to send messages. + * A Connection interface is passed to a WebSocket instance via the {@link WebSocket#onOpen(Connection)} to give the application access to the specifics of + * the current connection. This includes methods for sending frames and messages as well as methods for interpreting the flags and opcodes of the + * connection. */ - void onOpen(Connection connection); - - /** - * Called when an established websocket connection closes - * @param closeCode - * @param message - */ - void onClose(int closeCode, String message); - - /** - * A nested WebSocket interface for receiving text messages - */ - interface OnTextMessage extends WebSocket + public interface Connection { /** - * Called with a complete text message when all fragments have been received. - * The maximum size of text message that may be aggregated from multiple frames is set with {@link Connection#setMaxTextMessageSize(int)}. - * @param data The message + * Close the connection with normal close code. */ - void onMessage(String data); + void close(); + + /** Close the connection with specific closeCode and message. + * @param closeCode The close code to send, or -1 for no close code + * @param message The message to send or null for no message + */ + void close(int closeCode,String message); + + /** + * Enqueue a text message to be sent. + *

+ * It is possible that the message might be split up and fragmented to satisfy + * policies in place on the websocket. + * + * @param message the message text to send. + * @throws IOException + */ + void enqueTextMessage(String message) throws IOException; + + /** + * Get the websocket policy in use for this connection. + * @return connection specific websocket policy. + */ + WebSocketPolicy getPolicy(); + + /** + * Get the active scheme. "ws" (websocket) or "wss" (websocket secure) + * + * @return the active protocol scheme + */ + String getProtocol(); + + boolean isOpen(); } /** @@ -78,13 +87,13 @@ public interface WebSocket */ void onMessage(byte[] data, int offset, int length); } - + /** * A nested WebSocket interface for receiving control messages */ interface OnControl extends WebSocket { - /** + /** * Called when a control message has been received. * @param controlCode * @param data @@ -94,7 +103,7 @@ public interface WebSocket */ boolean onControl(byte controlCode,byte[] data, int offset, int length); } - + /** * A nested WebSocket interface for receiving any websocket frame */ @@ -110,176 +119,33 @@ public interface WebSocket * @return true if this call has completely handled the frame and no further processing is needed (including aggregation and/or message delivery) */ boolean onFrame(byte flags,byte opcode,byte[] data, int offset, int length); - + void onHandshake(FrameConnection connection); } - + /** - * A Connection interface is passed to a WebSocket instance via the {@link WebSocket#onOpen(Connection)} to - * give the application access to the specifics of the current connection. This includes methods - * for sending frames and messages as well as methods for interpreting the flags and opcodes of the connection. + * A nested WebSocket interface for receiving text messages */ - public interface Connection + interface OnTextMessage extends WebSocket { - String getProtocol(); - void sendMessage(String data) throws IOException; - void sendMessage(byte[] data, int offset, int length) throws IOException; - /** - * @deprecated Use {@link #close()} + * Called with a complete text message when all fragments have been received. + * The maximum size of text message that may be aggregated from multiple frames is set with {@link Connection#setMaxTextMessageSize(int)}. + * @param data The message */ - void disconnect(); - - /** - * Close the connection with normal close code. - */ - void close(); - - /** Close the connection with specific closeCode and message. - * @param closeCode The close code to send, or -1 for no close code - * @param message The message to send or null for no message - */ - void close(int closeCode,String message); - - boolean isOpen(); - - /** - * @param ms The time in ms that the connection can be idle before closing - */ - void setMaxIdleTime(int ms); - - /** - * @param size size<0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters - */ - void setMaxTextMessageSize(int size); - - /** - * @param size size<0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer - */ - void setMaxBinaryMessageSize(int size); - - /** - * @return The time in ms that the connection can be idle before closing - */ - int getMaxIdleTime(); - - /** - * Size in characters of the maximum text message to be received - * @return size <0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters - */ - int getMaxTextMessageSize(); - - /** - * Size in bytes of the maximum binary message to be received - * @return size <0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer - */ - int getMaxBinaryMessageSize(); + void onMessage(String data); } /** - * Frame Level Connection - *

The Connection interface at the level of sending/receiving frames rather than messages. - * Also contains methods to decode/generate flags and opcodes without using constants, so that - * code can be written to work with multiple drafts of the protocol. - * + * Called when an established websocket connection closes + * @param closeCode + * @param message */ - public interface FrameConnection extends Connection - { - /** - * @return The opcode of a binary message - */ - byte binaryOpcode(); - - /** - * @return The opcode of a text message - */ - byte textOpcode(); - - /** - * @return The opcode of a continuation frame - */ - byte continuationOpcode(); - - /** - * @return Mask for the FIN bit. - */ - byte finMask(); - - /** Set if frames larger than the frame buffer are handled with local fragmentations - * @param allowFragmentation - */ - void setAllowFrameFragmentation(boolean allowFragmentation); + void onClose(int closeCode, String message); - /** - * @param flags The flags bytes of a frame - * @return True of the flags indicate a final frame. - */ - boolean isMessageComplete(byte flags); - - /** - * @param opcode - * @return True if the opcode is for a control frame - */ - boolean isControl(byte opcode); - - /** - * @param opcode - * @return True if the opcode is for a text frame - */ - boolean isText(byte opcode); - - /** - * @param opcode - * @return True if the opcode is for a binary frame - */ - boolean isBinary(byte opcode); - - /** - * @param opcode - * @return True if the opcode is for a continuation frame - */ - boolean isContinuation(byte opcode); - - /** - * @param opcode - * @return True if the opcode is a close control - */ - boolean isClose(byte opcode); - - /** - * @param opcode - * @return True if the opcode is a ping control - */ - boolean isPing(byte opcode); - - /** - * @param opcode - * @return True if the opcode is a pong control - */ - boolean isPong(byte opcode); - - /** - * @return True if frames larger than the frame buffer are fragmented. - */ - boolean isAllowFrameFragmentation(); - - /** Send a control frame - * @param control - * @param data - * @param offset - * @param length - * @throws IOException - */ - void sendControl(byte control,byte[] data, int offset, int length) throws IOException; - - /** Send an arbitrary frame - * @param flags - * @param opcode - * @param data - * @param offset - * @param length - * @throws IOException - */ - void sendFrame(byte flags,byte opcode,byte[] data, int offset, int length) throws IOException; - } + /** + * Called when a new websocket connection is accepted. + * @param connection The Connection object to use to send messages. + */ + void onOpen(Connection connection); } diff --git a/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/api/WebSocket.java b/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/api/WebSocket.java index c83a9ed22c9..37939004e8f 100644 --- a/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/api/WebSocket.java +++ b/jetty-websocket/websocket-core/src/main/java/org/eclipse/jetty/websocket/api/WebSocket.java @@ -1,13 +1,76 @@ package org.eclipse.jetty.websocket.api; +import java.nio.ByteBuffer; +import java.util.concurrent.Future; + +import org.eclipse.jetty.websocket.frames.BaseFrame; +import org.eclipse.jetty.websocket.frames.BinaryFrame; +import org.eclipse.jetty.websocket.frames.CloseFrame; +import org.eclipse.jetty.websocket.frames.ControlFrame; +import org.eclipse.jetty.websocket.frames.DataFrame; +import org.eclipse.jetty.websocket.frames.PingFrame; +import org.eclipse.jetty.websocket.frames.TextFrame; + /** * Constants for WebSocket protocol as-defined in RFC-6455. */ -public class WebSocket +public interface WebSocket { /** * Per RFC 6455, section 1.3 - Opening Handshake - this version is "13" */ public final static int VERSION = 13; + + /* + * Connection + * - void terminateConnection(); + * - void terminateConnection(int statusCode); + * - void terminateConnection(int statusCode, String reason); + * - FutureCallback sendFrame(BaseFrame frame) + * - FutureCallback sendText(String text) + * - FutureCallback sendBinary(ByteBuffer payload) + * - FutureCallback sendBinary(byte buf[], int offset, int len) + * + * @OnWebSocketHandshake + * public void {methodname}(Connection conn) + * + * @OnWebSocketConnect + * public void {methodname}(Connection conn) + * + * @OnWebSocketDisconnect + * public void {methodname}(Connection conn) + * + * @OnWebSocketFrame(type=CloseFrame.class) + * public void {methodname}(CloseFrame frame); + * + * @OnWebSocketText + * public void {methodname}(String text); + * + * @OnWebSocketBinary + * public void {methodname}(byte buf[], int offset, int length); + * public void {methodname}(ByteBuffer buffer); + * + * @OnWebSocketClose + * public void {methodnamne}(int statusCode, String reason); + */ + + void onBinaryFrame(BinaryFrame frame); + + void onClose(int statusCode, String reason); + void onCloseFrame(CloseFrame frame); + + void onControlFrame(ControlFrame frame); + void onDataFrame(DataFrame frame); + void onHandshake(/* what params? */); + + void onOpen(); + void onTextFrame(TextFrame frame); + + void sendBinary(byte buf[]); + void sendBinary(ByteBuffer buffer); + + Future sendFrame(BaseFrame frame); + void sendPong(PingFrame frame); + void sendText(String message); }