Java: introducing websocket support.

1 files changed, 229 insertions, 0 deletions

diff --git a/src/java/javax/websocket/RemoteEndpoint.java b/src/java/javax/websocket/RemoteEndpoint.java
new file mode 100644
index 00000000..19c7a100
--- /dev/null
+++ b/src/java/javax/websocket/RemoteEndpoint.java
@@ -0,0 +1,229 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.websocket;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.Writer;
+import java.nio.ByteBuffer;
+import java.util.concurrent.Future;
+
+
+public interface RemoteEndpoint {
+
+    interface Async extends RemoteEndpoint {
+
+        /**
+         * Obtain the timeout (in milliseconds) for sending a message
+         * asynchronously. The default value is determined by
+         * {@link WebSocketContainer#getDefaultAsyncSendTimeout()}.
+         * @return  The current send timeout in milliseconds. A non-positive
+         *          value means an infinite timeout.
+         */
+        long getSendTimeout();
+
+        /**
+         * Set the timeout (in milliseconds) for sending a message
+         * asynchronously. The default value is determined by
+         * {@link WebSocketContainer#getDefaultAsyncSendTimeout()}.
+         * @param timeout   The new timeout for sending messages asynchronously
+         *                  in milliseconds. A non-positive value means an
+         *                  infinite timeout.
+         */
+        void setSendTimeout(long timeout);
+
+        /**
+         * Send the message asynchronously, using the SendHandler to signal to the
+         * client when the message has been sent.
+         * @param text          The text message to send
+         * @param completion    Used to signal to the client when the message has
+         *                      been sent
+         */
+        void sendText(String text, SendHandler completion);
+
+        /**
+         * Send the message asynchronously, using the Future to signal to the
+         * client when the message has been sent.
+         * @param text          The text message to send
+         * @return A Future that signals when the message has been sent.
+         */
+        Future<Void> sendText(String text);
+
+        /**
+         * Send the message asynchronously, using the Future to signal to the client
+         * when the message has been sent.
+         * @param data          The text message to send
+         * @return A Future that signals when the message has been sent.
+         * @throws IllegalArgumentException if {@code data} is {@code null}.
+         */
+        Future<Void> sendBinary(ByteBuffer data);
+
+        /**
+         * Send the message asynchronously, using the SendHandler to signal to the
+         * client when the message has been sent.
+         * @param data          The text message to send
+         * @param completion    Used to signal to the client when the message has
+         *                      been sent
+         * @throws IllegalArgumentException if {@code data} or {@code completion}
+         *                      is {@code null}.
+         */
+        void sendBinary(ByteBuffer data, SendHandler completion);
+
+        /**
+         * Encodes object as a message and sends it asynchronously, using the
+         * Future to signal to the client when the message has been sent.
+         * @param obj           The object to be sent.
+         * @return A Future that signals when the message has been sent.
+         * @throws IllegalArgumentException if {@code obj} is {@code null}.
+         */
+        Future<Void> sendObject(Object obj);
+
+        /**
+         * Encodes object as a message and sends it asynchronously, using the
+         * SendHandler to signal to the client when the message has been sent.
+         * @param obj           The object to be sent.
+         * @param completion    Used to signal to the client when the message has
+         *                      been sent
+         * @throws IllegalArgumentException if {@code obj} or
+         *                      {@code completion} is {@code null}.
+         */
+        void sendObject(Object obj, SendHandler completion);
+
+    }
+
+    interface Basic extends RemoteEndpoint {
+
+        /**
+         * Send the message, blocking until the message is sent.
+         * @param text  The text message to send.
+         * @throws IllegalArgumentException if {@code text} is {@code null}.
+         * @throws IOException if an I/O error occurs during the sending of the
+         *                     message.
+         */
+        void sendText(String text) throws IOException;
+
+        /**
+         * Send the message, blocking until the message is sent.
+         * @param data  The binary message to send
+         * @throws IllegalArgumentException if {@code data} is {@code null}.
+         * @throws IOException if an I/O error occurs during the sending of the
+         *                     message.
+         */
+        void sendBinary(ByteBuffer data) throws IOException;
+
+        /**
+         * Sends part of a text message to the remote endpoint. Once the first part
+         * of a message has been sent, no other text or binary messages may be sent
+         * until all remaining parts of this message have been sent.
+         *
+         * @param fragment  The partial message to send
+         * @param isLast    <code>true</code> if this is the last part of the
+         *                  message, otherwise <code>false</code>
+         * @throws IllegalArgumentException if {@code fragment} is {@code null}.
+         * @throws IOException if an I/O error occurs during the sending of the
+         *                     message.
+         */
+        void sendText(String fragment, boolean isLast) throws IOException;
+
+        /**
+         * Sends part of a binary message to the remote endpoint. Once the first
+         * part of a message has been sent, no other text or binary messages may be
+         * sent until all remaining parts of this message have been sent.
+         *
+         * @param partialByte   The partial message to send
+         * @param isLast        <code>true</code> if this is the last part of the
+         *                      message, otherwise <code>false</code>
+         * @throws IllegalArgumentException if {@code partialByte} is
+         *                     {@code null}.
+         * @throws IOException if an I/O error occurs during the sending of the
+         *                     message.
+         */
+        void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException;
+
+        OutputStream getSendStream() throws IOException;
+
+        Writer getSendWriter() throws IOException;
+
+        /**
+         * Encodes object as a message and sends it to the remote endpoint.
+         * @param data  The object to be sent.
+         * @throws EncodeException if there was a problem encoding the
+         *                     {@code data} object as a websocket message.
+         * @throws IllegalArgumentException if {@code data} is {@code null}.
+         * @throws IOException if an I/O error occurs during the sending of the
+         *                     message.
+         */
+        void sendObject(Object data) throws IOException, EncodeException;
+
+    }
+    /**
+     * Enable or disable the batching of outgoing messages for this endpoint. If
+     * batching is disabled when it was previously enabled then this method will
+     * block until any currently batched messages have been written.
+     *
+     * @param batchingAllowed   New setting
+     * @throws IOException      If changing the value resulted in a call to
+     *                          {@link #flushBatch()} and that call threw an
+     *                          {@link IOException}.
+     */
+    void setBatchingAllowed(boolean batchingAllowed) throws IOException;
+
+    /**
+     * Obtains the current batching status of the endpoint.
+     *
+     * @return <code>true</code> if batching is enabled, otherwise
+     *         <code>false</code>.
+     */
+    boolean getBatchingAllowed();
+
+    /**
+     * Flush any currently batched messages to the remote endpoint. This method
+     * will block until the flush completes.
+     *
+     * @throws IOException If an I/O error occurs while flushing
+     */
+    void flushBatch() throws IOException;
+
+    /**
+     * Send a ping message blocking until the message has been sent. Note that
+     * if a message is in the process of being sent asynchronously, this method
+     * will block until that message and this ping has been sent.
+     *
+     * @param applicationData   The payload for the ping message
+     *
+     * @throws IOException If an I/O error occurs while sending the ping
+     * @throws IllegalArgumentException if the applicationData is too large for
+     *         a control message (max 125 bytes)
+     */
+    void sendPing(ByteBuffer applicationData)
+            throws IOException, IllegalArgumentException;
+
+    /**
+     * Send a pong message blocking until the message has been sent. Note that
+     * if a message is in the process of being sent asynchronously, this method
+     * will block until that message and this pong has been sent.
+     *
+     * @param applicationData   The payload for the pong message
+     *
+     * @throws IOException If an I/O error occurs while sending the pong
+     * @throws IllegalArgumentException if the applicationData is too large for
+     *         a control message (max 125 bytes)
+     */
+    void sendPong(ByteBuffer applicationData)
+            throws IOException, IllegalArgumentException;
+}
+