Java tutorial
/* * 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; }