xref: /unit/src/java/javax/websocket/RemoteEndpoint.java (revision 1157:7ae152bda303)
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