1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package javax.websocket; 18 19 import java.io.IOException; 20 import java.io.OutputStream; 21 import java.io.Writer; 22 import java.nio.ByteBuffer; 23 import java.util.concurrent.Future; 24 25 26 public interface RemoteEndpoint { 27 28 interface Async extends RemoteEndpoint { 29 30 /** 31 * Obtain the timeout (in milliseconds) for sending a message 32 * asynchronously. The default value is determined by 33 * {@link WebSocketContainer#getDefaultAsyncSendTimeout()}. 34 * @return The current send timeout in milliseconds. A non-positive 35 * value means an infinite timeout. 36 */ getSendTimeout()37 long getSendTimeout(); 38 39 /** 40 * Set the timeout (in milliseconds) for sending a message 41 * asynchronously. The default value is determined by 42 * {@link WebSocketContainer#getDefaultAsyncSendTimeout()}. 43 * @param timeout The new timeout for sending messages asynchronously 44 * in milliseconds. A non-positive value means an 45 * infinite timeout. 46 */ setSendTimeout(long timeout)47 void setSendTimeout(long timeout); 48 49 /** 50 * Send the message asynchronously, using the SendHandler to signal to the 51 * client when the message has been sent. 52 * @param text The text message to send 53 * @param completion Used to signal to the client when the message has 54 * been sent 55 */ sendText(String text, SendHandler completion)56 void sendText(String text, SendHandler completion); 57 58 /** 59 * Send the message asynchronously, using the Future to signal to the 60 * client when the message has been sent. 61 * @param text The text message to send 62 * @return A Future that signals when the message has been sent. 63 */ sendText(String text)64 Future<Void> sendText(String text); 65 66 /** 67 * Send the message asynchronously, using the Future to signal to the client 68 * when the message has been sent. 69 * @param data The text message to send 70 * @return A Future that signals when the message has been sent. 71 * @throws IllegalArgumentException if {@code data} is {@code null}. 72 */ sendBinary(ByteBuffer data)73 Future<Void> sendBinary(ByteBuffer data); 74 75 /** 76 * Send the message asynchronously, using the SendHandler to signal to the 77 * client when the message has been sent. 78 * @param data The text message to send 79 * @param completion Used to signal to the client when the message has 80 * been sent 81 * @throws IllegalArgumentException if {@code data} or {@code completion} 82 * is {@code null}. 83 */ sendBinary(ByteBuffer data, SendHandler completion)84 void sendBinary(ByteBuffer data, SendHandler completion); 85 86 /** 87 * Encodes object as a message and sends it asynchronously, using the 88 * Future to signal to the client when the message has been sent. 89 * @param obj The object to be sent. 90 * @return A Future that signals when the message has been sent. 91 * @throws IllegalArgumentException if {@code obj} is {@code null}. 92 */ sendObject(Object obj)93 Future<Void> sendObject(Object obj); 94 95 /** 96 * Encodes object as a message and sends it asynchronously, using the 97 * SendHandler to signal to the client when the message has been sent. 98 * @param obj The object to be sent. 99 * @param completion Used to signal to the client when the message has 100 * been sent 101 * @throws IllegalArgumentException if {@code obj} or 102 * {@code completion} is {@code null}. 103 */ sendObject(Object obj, SendHandler completion)104 void sendObject(Object obj, SendHandler completion); 105 106 } 107 108 interface Basic extends RemoteEndpoint { 109 110 /** 111 * Send the message, blocking until the message is sent. 112 * @param text The text message to send. 113 * @throws IllegalArgumentException if {@code text} is {@code null}. 114 * @throws IOException if an I/O error occurs during the sending of the 115 * message. 116 */ sendText(String text)117 void sendText(String text) throws IOException; 118 119 /** 120 * Send the message, blocking until the message is sent. 121 * @param data The binary message to send 122 * @throws IllegalArgumentException if {@code data} is {@code null}. 123 * @throws IOException if an I/O error occurs during the sending of the 124 * message. 125 */ sendBinary(ByteBuffer data)126 void sendBinary(ByteBuffer data) throws IOException; 127 128 /** 129 * Sends part of a text message to the remote endpoint. Once the first part 130 * of a message has been sent, no other text or binary messages may be sent 131 * until all remaining parts of this message have been sent. 132 * 133 * @param fragment The partial message to send 134 * @param isLast <code>true</code> if this is the last part of the 135 * message, otherwise <code>false</code> 136 * @throws IllegalArgumentException if {@code fragment} is {@code null}. 137 * @throws IOException if an I/O error occurs during the sending of the 138 * message. 139 */ sendText(String fragment, boolean isLast)140 void sendText(String fragment, boolean isLast) throws IOException; 141 142 /** 143 * Sends part of a binary message to the remote endpoint. Once the first 144 * part of a message has been sent, no other text or binary messages may be 145 * sent until all remaining parts of this message have been sent. 146 * 147 * @param partialByte The partial message to send 148 * @param isLast <code>true</code> if this is the last part of the 149 * message, otherwise <code>false</code> 150 * @throws IllegalArgumentException if {@code partialByte} is 151 * {@code null}. 152 * @throws IOException if an I/O error occurs during the sending of the 153 * message. 154 */ sendBinary(ByteBuffer partialByte, boolean isLast)155 void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException; 156 getSendStream()157 OutputStream getSendStream() throws IOException; 158 getSendWriter()159 Writer getSendWriter() throws IOException; 160 161 /** 162 * Encodes object as a message and sends it to the remote endpoint. 163 * @param data The object to be sent. 164 * @throws EncodeException if there was a problem encoding the 165 * {@code data} object as a websocket message. 166 * @throws IllegalArgumentException if {@code data} is {@code null}. 167 * @throws IOException if an I/O error occurs during the sending of the 168 * message. 169 */ sendObject(Object data)170 void sendObject(Object data) throws IOException, EncodeException; 171 172 } 173 /** 174 * Enable or disable the batching of outgoing messages for this endpoint. If 175 * batching is disabled when it was previously enabled then this method will 176 * block until any currently batched messages have been written. 177 * 178 * @param batchingAllowed New setting 179 * @throws IOException If changing the value resulted in a call to 180 * {@link #flushBatch()} and that call threw an 181 * {@link IOException}. 182 */ setBatchingAllowed(boolean batchingAllowed)183 void setBatchingAllowed(boolean batchingAllowed) throws IOException; 184 185 /** 186 * Obtains the current batching status of the endpoint. 187 * 188 * @return <code>true</code> if batching is enabled, otherwise 189 * <code>false</code>. 190 */ getBatchingAllowed()191 boolean getBatchingAllowed(); 192 193 /** 194 * Flush any currently batched messages to the remote endpoint. This method 195 * will block until the flush completes. 196 * 197 * @throws IOException If an I/O error occurs while flushing 198 */ flushBatch()199 void flushBatch() throws IOException; 200 201 /** 202 * Send a ping message blocking until the message has been sent. Note that 203 * if a message is in the process of being sent asynchronously, this method 204 * will block until that message and this ping has been sent. 205 * 206 * @param applicationData The payload for the ping message 207 * 208 * @throws IOException If an I/O error occurs while sending the ping 209 * @throws IllegalArgumentException if the applicationData is too large for 210 * a control message (max 125 bytes) 211 */ sendPing(ByteBuffer applicationData)212 void sendPing(ByteBuffer applicationData) 213 throws IOException, IllegalArgumentException; 214 215 /** 216 * Send a pong message blocking until the message has been sent. Note that 217 * if a message is in the process of being sent asynchronously, this method 218 * will block until that message and this pong has been sent. 219 * 220 * @param applicationData The payload for the pong message 221 * 222 * @throws IOException If an I/O error occurs while sending the pong 223 * @throws IllegalArgumentException if the applicationData is too large for 224 * a control message (max 125 bytes) 225 */ sendPong(ByteBuffer applicationData)226 void sendPong(ByteBuffer applicationData) 227 throws IOException, IllegalArgumentException; 228 } 229 230