+ * A valid WebSocket should do one of the following: + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int NORMAL = 1000; + + /** + * 1001 indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int SHUTDOWN = 1001; + + /** + * 1002 indicates that an endpoint is terminating the connection due to a protocol error. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int PROTOCOL = 1002; + + /** + * 1003 indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands + * only text data MAY send this if it receives a binary message). + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int BAD_DATA = 1003; + + /** + * Reserved. The specific meaning might be defined in the future. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int UNDEFINED = 1004; + + /** + * 1005 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting + * a status code to indicate that no status code was actually present. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int NO_CODE = 1005; + + /** + * 1006 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting + * a status code to indicate that the connection was closed abnormally, e.g., without sending or receiving a Close control frame. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int NO_CLOSE = 1006; + + /** + * 1007 indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the + * message (e.g., non-UTF-8 [RFC3629] data within a text message). + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int BAD_PAYLOAD = 1007; + + /** + * 1008 indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code + * that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the + * policy. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int POLICY_VIOLATION = 1008; + + /** + * 1009 indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int MESSAGE_TOO_LARGE = 1009; + + /** + * 1010 indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the + * server didn't return them in the response message of the WebSocket handshake. The list of extensions that are needed SHOULD appear in the /reason/ part + * of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int REQUIRED_EXTENSION = 1010; + + /** + * 1011 indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request. + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes. + */ + public final static int SERVER_ERROR = 1011; + + /** + * 1012 indicates that the service is restarted. a client may reconnect, and if it chooses to do, should reconnect using a randomized delay of 5 - 30s. + *
+ * See [hybi] Additional WebSocket Close Error Codes + */ + public final static int SERVICE_RESTART = 1012; + + /** + * 1013 indicates that the service is experiencing overload. a client should only connect to a different IP (when there are multiple for the target) or + * reconnect to the same IP upon user action. + *
+ * See [hybi] Additional WebSocket Close Error Codes + */ + public final static int TRY_AGAIN_LATER = 1013; + + /** + * 1015 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting + * a status code to indicate that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can't be verified). + *
+ * See RFC 6455, Section 7.4.1 Defined Status Codes.
+ */
+ public final static int FAILED_TLS_HANDSHAKE = 1015;
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/SuspendToken.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/SuspendToken.java
new file mode 100644
index 00000000000..d64c01da96d
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/SuspendToken.java
@@ -0,0 +1,30 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api;
+
+/**
+ * Connection suspend token
+ */
+public interface SuspendToken
+{
+ /**
+ * Resume a previously suspended connection.
+ */
+ void resume();
+}
\ No newline at end of file
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/UpgradeException.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/UpgradeException.java
new file mode 100644
index 00000000000..6e353eba081
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/UpgradeException.java
@@ -0,0 +1,46 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api;
+
+/**
+ * Exception during WebSocket Upgrade Handshake.
+ */
+@SuppressWarnings("serial")
+public class UpgradeException extends WebSocketException
+{
+ public UpgradeException()
+ {
+ super();
+ }
+
+ public UpgradeException(String message)
+ {
+ super(message);
+ }
+
+ public UpgradeException(String message, Throwable cause)
+ {
+ super(message,cause);
+ }
+
+ public UpgradeException(Throwable cause)
+ {
+ super(cause);
+ }
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/UpgradeRequest.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/UpgradeRequest.java
new file mode 100644
index 00000000000..825b1fce9a2
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/UpgradeRequest.java
@@ -0,0 +1,59 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api;
+
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.jetty.websocket.api.extensions.ExtensionConfig;
+
+public interface UpgradeRequest
+{
+ public void addExtensions(String... extConfigs);
+
+ public Map
+ * This means that the websocket endpoint was valid, but the conditions to use a WebSocket resulted in a forbidden access.
+ *
+ * Use this when the origin or authentication is invalid.
+ *
+ * @param message
+ * the short 1 line detail message about the forbidden response
+ * @throws IOException
+ */
+ public void sendForbidden(String message) throws IOException;
+
+ /**
+ * Set the accepted WebSocket Protocol.
+ *
+ * @param protocol
+ * the protocol to list as accepted
+ */
+ public void setAcceptedSubProtocol(String protocol);
+
+ /**
+ * Set the list of extensions that are approved for use with this websocket.
+ *
+ * This is Advanced usage of the {@link WebSocketCreator} to allow for a custom set of negotiated extensions.
+ *
+ * Notes:
+ *
+ * Convenient abstract class to base standard WebSocket implementations off of.
+ */
+public class WebSocketAdapter implements WebSocketListener
+{
+ private WebSocketConnection connection;
+ private WebSocketBlockingConnection blocking;
+
+ public WebSocketBlockingConnection getBlockingConnection()
+ {
+ return blocking;
+ }
+
+ public WebSocketConnection getConnection()
+ {
+ return connection;
+ }
+
+ public boolean isConnected()
+ {
+ return (connection != null) && (connection.isOpen());
+ }
+
+ public boolean isNotConnected()
+ {
+ return (connection == null) || (!connection.isOpen());
+ }
+
+ @Override
+ public void onWebSocketBinary(byte[] payload, int offset, int len)
+ {
+ /* do nothing */
+ }
+
+ @Override
+ public void onWebSocketClose(int statusCode, String reason)
+ {
+ this.connection = null;
+ }
+
+ @Override
+ public void onWebSocketConnect(WebSocketConnection connection)
+ {
+ this.connection = connection;
+ this.blocking = new WebSocketBlockingConnection(this.connection);
+ }
+
+ @Override
+ public void onWebSocketException(WebSocketException error)
+ {
+ /* do nothing */
+ }
+
+ @Override
+ public void onWebSocketText(String message)
+ {
+ /* do nothing */
+ }
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketBehavior.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketBehavior.java
new file mode 100644
index 00000000000..ad4f452ab5f
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketBehavior.java
@@ -0,0 +1,31 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api;
+
+/**
+ * Behavior for how the WebSocket should operate.
+ *
+ * This dictated by the RFC 6455 spec in various places, where certain behavior must be performed depending on
+ * operation as a CLIENT vs a SERVER
+ */
+public enum WebSocketBehavior
+{
+ CLIENT,
+ SERVER;
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketConnection.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketConnection.java
new file mode 100644
index 00000000000..c24ebe60e82
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketConnection.java
@@ -0,0 +1,134 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api;
+
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.net.URI;
+import java.nio.ByteBuffer;
+import java.util.concurrent.Future;
+
+/**
+ * Connection interface for WebSocket protocol RFC-6455.
+ */
+public interface WebSocketConnection
+{
+ /**
+ * Send a websocket Close frame, without a status code or reason.
+ *
+ * Basic usage: results in an non-blocking async write, then connection close.
+ *
+ * @see StatusCode
+ * @see #close(int, String)
+ */
+ public void close();
+
+ /**
+ * Send a websocket Close frame, with status code.
+ *
+ * Advanced usage: results in an non-blocking async write, then connection close.
+ *
+ * @param statusCode
+ * the status code
+ * @param reason
+ * the (optional) reason. (can be null for no reason)
+ * @see StatusCode
+ */
+ public void close(int statusCode, String reason);
+
+ /**
+ * Is the connection open.
+ *
+ * @return true if open
+ */
+ public boolean isOpen();
+
+ /**
+ * Suspend a the incoming read events on the connection.
+ *
+ * @return the suspend token suitable for resuming the reading of data on the connection.
+ */
+ SuspendToken suspend();
+
+ /**
+ * Get the address of the remote side.
+ *
+ * @return the remote side address
+ */
+ public InetSocketAddress getRemoteAddress();
+
+ /**
+ * Get the address of the local side.
+ *
+ * @return the local side address
+ */
+ public InetSocketAddress getLocalAddress();
+
+ /**
+ * Get the Request URI
+ *
+ * @return the requested URI
+ */
+ public URI getRequestURI();
+
+ /**
+ * Access the (now read-only) {@link WebSocketPolicy} in use for this connection.
+ *
+ * @return the policy in use
+ */
+ WebSocketPolicy getPolicy();
+
+ /**
+ * Get the SubProtocol in use for this connection.
+ *
+ * @return the negotiated sub protocol name in use for this connection, can be null if there is no sub-protocol negotiated.
+ */
+ String getSubProtocol();
+
+ /**
+ * Send a single ping messages.
+ *
+ * NIO style with callbacks, allows for knowledge of successful ping send.
+ *
+ * Use @OnWebSocketFrame and monitor Pong frames
+ */
+
+ * NIO style with callbacks, allows for concurrent results of the write operation.
+ */
+
+ * NIO style with callbacks, allows for concurrent results of the write operation.
+ */
+
+ * NIO style with callbacks, allows for concurrent results of the entire write operation. (Callback is only called once at the end of processing all of the
+ * messages)
+ */
+
+ * The underlying {@link WebSocketConnection} will be considered closed at this point.
+ *
+ * @param statusCode
+ * the close status code. (See {@link StatusCode})
+ * @param reason
+ * the optional reason for the close.
+ */
+ void onWebSocketClose(int statusCode, String reason);
+
+ /**
+ * A WebSocketConnection has connected successfully and is ready to be used.
+ *
+ * Note: It is a good idea to track this connection as a field in your object so that you can write messages back.
+ *
+ * @param connection
+ * the connection to use to send messages on.
+ */
+ void onWebSocketConnect(WebSocketConnection connection);
+
+ /**
+ * A WebSocket exception has occurred.
+ *
+ * Usually this occurs from bad / malformed incoming packets. (example: bad UTF8 data, frames that are too big, violations of the spec)
+ *
+ * This will result in the {@link WebSocketConnection} being closed by the implementing side.
+ *
+ * Note: you will receive no {@link #onWebSocketClose(int, String)} as this condition results in the API calling
+ * {@link WebSocketConnection#close(int, String)} for you.
+ *
+ * @param error
+ * the error that occurred.
+ */
+ void onWebSocketException(WebSocketException error);
+
+ /**
+ * A WebSocket Text frame was received.
+ *
+ * @param message
+ */
+ void onWebSocketText(String message);
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketPolicy.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketPolicy.java
new file mode 100644
index 00000000000..026eaa8ccac
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/WebSocketPolicy.java
@@ -0,0 +1,208 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api;
+
+
+/**
+ * Settings for WebSocket operations.
+ */
+public class WebSocketPolicy
+{
+ public static WebSocketPolicy newClientPolicy()
+ {
+ return new WebSocketPolicy(WebSocketBehavior.CLIENT);
+ }
+
+ public static WebSocketPolicy newServerPolicy()
+ {
+ return new WebSocketPolicy(WebSocketBehavior.SERVER);
+ }
+
+ /**
+ * Automatically fragment large frames.
+ *
+ * If frames are encountered at size larger than {@link #maxPayloadSize} then they are automatically fragmented into pieces fitting within the
+ * maxPayloadSize.
+ *
+ * Default: false
+ */
+ private boolean autoFragment = false;
+
+ /**
+ * The maximum allowed payload size (validated in both directions)
+ *
+ * Default: 65536 (64K)
+ */
+ private int maxPayloadSize = 65536;
+
+ /**
+ * The maximum size of a text message during parsing/generating.
+ *
+ * Default: 16384 (16 K)
+ */
+ private int maxTextMessageSize = 16384;
+
+ /**
+ * The maximum size of a binary message during parsing/generating.
+ *
+ * Default: -1 (no validation)
+ */
+ private int maxBinaryMessageSize = -1;
+
+ /**
+ * Maximum Message Buffer size, which is also the max frame byte size.
+ *
+ * Default: 65536 (64 K)
+ */
+ private int bufferSize = 65536;
+
+ // TODO: change bufferSize to windowSize for FrameBytes logic?
+
+ /**
+ * The time in ms (milliseconds) that a websocket may be idle before closing.
+ *
+ * Default: 300000 (ms)
+ */
+ private int idleTimeout = 300000;
+
+ /**
+ * Behavior of the websockets
+ */
+ private final WebSocketBehavior behavior;
+
+ public WebSocketPolicy(WebSocketBehavior behavior)
+ {
+ this.behavior = behavior;
+ }
+
+ public void assertValidBinaryMessageSize(int requestedSize)
+ {
+ if (maxBinaryMessageSize > 0)
+ {
+ // validate it
+ if (requestedSize > maxBinaryMessageSize)
+ {
+ throw new MessageTooLargeException("Requested binary message size [" + requestedSize + "] exceeds maximum size [" + maxBinaryMessageSize + "]");
+ }
+ }
+ }
+
+ public void assertValidPayloadLength(int payloadLength)
+ {
+ // validate to buffer sizes
+ if (payloadLength > maxPayloadSize)
+ {
+ throw new MessageTooLargeException("Requested payload length [" + payloadLength + "] exceeds maximum size [" + maxPayloadSize + "]");
+ }
+ }
+
+ public void assertValidTextMessageSize(int requestedSize)
+ {
+ if (maxTextMessageSize > 0)
+ {
+ // validate it
+ if (requestedSize > maxTextMessageSize)
+ {
+ throw new MessageTooLargeException("Requested text message size [" + requestedSize + "] exceeds maximum size [" + maxTextMessageSize + "]");
+ }
+ }
+ }
+
+ public WebSocketPolicy clonePolicy()
+ {
+ WebSocketPolicy clone = new WebSocketPolicy(this.behavior);
+ clone.autoFragment = this.autoFragment;
+ clone.idleTimeout = this.idleTimeout;
+ clone.bufferSize = this.bufferSize;
+ clone.maxPayloadSize = this.maxPayloadSize;
+ clone.maxBinaryMessageSize = this.maxBinaryMessageSize;
+ clone.maxTextMessageSize = this.maxTextMessageSize;
+ return clone;
+ }
+
+ public WebSocketBehavior getBehavior()
+ {
+ return behavior;
+ }
+
+ public int getBufferSize()
+ {
+ return bufferSize;
+ }
+
+ public int getIdleTimeout()
+ {
+ return idleTimeout;
+ }
+
+ public int getMaxBinaryMessageSize()
+ {
+ return maxBinaryMessageSize;
+ }
+
+ public int getMaxPayloadSize()
+ {
+ return maxPayloadSize;
+ }
+
+ public int getMaxTextMessageSize()
+ {
+ return maxTextMessageSize;
+ }
+
+ public boolean isAutoFragment()
+ {
+ return autoFragment;
+ }
+
+ public void setAutoFragment(boolean autoFragment)
+ {
+ this.autoFragment = autoFragment;
+ }
+
+ public void setBufferSize(int bufferSize)
+ {
+ this.bufferSize = bufferSize;
+ }
+
+ public void setIdleTimeout(int idleTimeout)
+ {
+ this.idleTimeout = idleTimeout;
+ }
+
+ public void setMaxBinaryMessageSize(int maxBinaryMessageSize)
+ {
+ this.maxBinaryMessageSize = maxBinaryMessageSize;
+ }
+
+ public void setMaxPayloadSize(int maxPayloadSize)
+ {
+ if (maxPayloadSize < bufferSize)
+ {
+ throw new IllegalStateException("Cannot have payload size be smaller than buffer size");
+ }
+ this.maxPayloadSize = maxPayloadSize;
+ }
+
+ public void setMaxTextMessageSize(int maxTextMessageSize)
+ {
+ this.maxTextMessageSize = maxTextMessageSize;
+ }
+
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketClose.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketClose.java
new file mode 100644
index 00000000000..8c322819311
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketClose.java
@@ -0,0 +1,46 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.eclipse.jetty.websocket.api.WebSocketConnection;
+
+/**
+ * Annotation for tagging methods to receive connection close events.
+ *
+ * Acceptable method patterns.
+ * Only 1 acceptable method pattern for this annotation.
+ * Note: any frame derived from {@link WebSocketFrame} is acceptable to use as the last parameter here.
+ *
+ * Acceptable method patterns.
+ * Acceptable method patterns.
+ * Text Message Versions
+ *
+ * Binary Message Versions
+ *
+ * That work is performed by the two {@link FrameHandler} implementations for incoming and outgoing frame handling.
+ */
+public interface Extension
+{
+ /**
+ * Create an instance of a Incoming {@link FrameHandler} for working with frames destined for the End User WebSocket Object.
+ *
+ * @return the frame handler for incoming frames.
+ */
+ public FrameHandler createIncomingFrameHandler();
+
+ /**
+ * Create an instance of a Outgoing {@link FrameHandler} for working with frames destined for the Network Bytes Layer.
+ *
+ * @return the frame handler for outgoing frames.
+ */
+ public FrameHandler createOutgoingFrameHandler();
+
+ /**
+ * The active configuration for this extension.
+ *
+ * @return the configuration for this extension. never null.
+ */
+ public ExtensionConfig getConfig();
+
+ /**
+ * The
+ * Also known as the
+ * This is an end-user accessible class.
+ */
+public class WebSocketBlockingConnection
+{
+ private static final String CONTEXT_BINARY = "BLOCKING_BINARY";
+ private static final String CONTEXT_TEXT = "BLOCKING_TEXT";
+ private final WebSocketConnection conn;
+
+ public WebSocketBlockingConnection(WebSocketConnection conn)
+ {
+ this.conn = conn;
+ }
+
+ /**
+ * Send a binary message.
+ *
+ * Basic usage, results in a blocking write.
+ */
+ public void write(byte[] data, int offset, int length) throws IOException
+ {
+ try
+ {
+ Future
+ * Basic usage, results in a blocking write.
+ */
+ public void write(String message) throws IOException
+ {
+ try
+ {
+ Future
+ *
+ *
+ * @param extensions
+ * the list of extensions to use.
+ */
+ public void setExtensions(List
+ * Note: methodName can be any name you want to use.
+ *
+ *
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value =
+{ ElementType.METHOD })
+public @interface OnWebSocketClose
+{
+ /* no config */
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketConnect.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketConnect.java
new file mode 100644
index 00000000000..26e0df1d702
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketConnect.java
@@ -0,0 +1,45 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.eclipse.jetty.websocket.api.WebSocketConnection;
+
+/**
+ * Annotation for tagging methods to receive connection open events.
+ * public void methodName(int statusCode, String reason)public void methodName({@link WebSocketConnection} conn, int statusCode, String reason)
+ * Note: methodName can be any name you want to use.
+ *
+ *
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value =
+{ ElementType.METHOD })
+public @interface OnWebSocketConnect
+{
+ /* no config */
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketFrame.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketFrame.java
new file mode 100644
index 00000000000..360b9f763ba
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketFrame.java
@@ -0,0 +1,48 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.eclipse.jetty.websocket.api.WebSocketConnection;
+
+/**
+ * (ADVANCED) Annotation for tagging methods to receive frame events.
+ * public void methodName({@link WebSocketConnection} conn)
+ * Note: methodName can be any name you want to use.
+ *
+ *
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value =
+{ ElementType.METHOD })
+public @interface OnWebSocketFrame
+{
+ /* no config */
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketMessage.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketMessage.java
new file mode 100644
index 00000000000..f46e0a52298
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/OnWebSocketMessage.java
@@ -0,0 +1,61 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api.annotations;
+
+import java.io.Reader;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.eclipse.jetty.websocket.api.WebSocketConnection;
+
+/**
+ * Annotation for tagging methods to receive Binary or Text Message events.
+ * public void methodName({@link WebSocketFrame} frame)public void methodName({@link WebSocketConnection} conn, {@link WebSocketFrame} frame)
+ * Note: methodName can be any name you want to use.
+ *
+ *
+ * Note: that the {@link Reader} in this case will always use UTF-8 encoding/charset (this is dictated by the RFC 6455 spec for Text Messages. If you need to
+ * use a non-UTF-8 encoding/charset, you are instructed to use the binary messaging techniques.
+ * public void methodName(String text)public void methodName({@link WebSocketConnection} conn, String text)public void methodName(Reader reader)public void methodName({@link WebSocketConnection} conn, Reader reader)
+ *
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value =
+{ ElementType.METHOD })
+public @interface OnWebSocketMessage
+{
+ /* no config */
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/WebSocket.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/WebSocket.java
new file mode 100644
index 00000000000..21eb65948fd
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/annotations/WebSocket.java
@@ -0,0 +1,43 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Tags a POJO as being a WebSocket class.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value =
+{ ElementType.TYPE })
+public @interface WebSocket
+{
+ int maxBinarySize() default -2;
+
+ int maxBufferSize() default -2;
+
+ int maxIdleTime() default -2;
+
+ int maxTextSize() default -2;
+}
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/extensions/Extension.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/extensions/Extension.java
new file mode 100644
index 00000000000..aa8425a0fa5
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/extensions/Extension.java
@@ -0,0 +1,55 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api.extensions;
+
+/**
+ * Interface for WebSocket Extensions.
+ * public void methodName(byte buf[], int offset, int length)public void methodName({@link WebSocketConnection} conn, byte buf[], int offset, int length)public void methodName(InputStream stream)public void methodName({@link WebSocketConnection} conn, InputStream stream)Sec-WebSocket-Extensions name for this extension.
+ * extension-token per Section 9.1. Negotiating Extensions.
+ */
+ public String getName();
+}
\ No newline at end of file
diff --git a/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/extensions/ExtensionConfig.java b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/extensions/ExtensionConfig.java
new file mode 100644
index 00000000000..b03e447a90b
--- /dev/null
+++ b/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/extensions/ExtensionConfig.java
@@ -0,0 +1,41 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2012 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.api.extensions;
+
+import java.util.Set;
+
+/**
+ * Represents an Extension Configuration, as seen during the connection Handshake process.
+ */
+public interface ExtensionConfig
+{
+ public String getName();
+
+ public int getParameter(String key, int defValue);
+
+ public String getParameter(String key, String defValue);
+
+ public String getParameterizedName();
+
+ public Set