1 //
2 // ========================================================================
3 // Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
8 //
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
11 //
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
14 //
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
17 //
18
19 package org.eclipse.jetty.websocket.api;
20
21 import java.io.IOException;
22 import java.nio.ByteBuffer;
23 import java.util.concurrent.Future;
24
25 public interface RemoteEndpoint
26 {
27 /**
28 * Send a binary message, returning when all bytes of the message has been transmitted.
29 * <p>
30 * Note: this is a blocking call
31 *
32 * @param data
33 * the message to be sent
34 * @throws IOException
35 * if unable to send the bytes
36 */
37 void sendBytes(ByteBuffer data) throws IOException;
38
39 /**
40 * Initiates the asynchronous transmission of a binary message. This method returns before the message is
41 * transmitted. Developers may use the returned
42 * Future object to track progress of the transmission.
43 *
44 * @param data
45 * the data being sent
46 * @return the Future object representing the send operation.
47 */
48 Future<Void> sendBytesByFuture(ByteBuffer data);
49
50 /**
51 * Initiates the asynchronous transmission of a binary message. This method returns before the message is
52 * transmitted. Developers may provide a callback to
53 * be notified when the message has been transmitted or resulted in an error.
54 *
55 * @param data
56 * the data being sent
57 * @param callback
58 * callback to notify of success or failure of the write operation
59 */
60 void sendBytes(ByteBuffer data, WriteCallback callback);
61
62 /**
63 * Send a binary message in pieces, blocking until all of the message has been transmitted. The runtime reads the
64 * message in order. Non-final pieces are
65 * sent with isLast set to false. The final piece must be sent with isLast set to true.
66 *
67 * @param fragment
68 * the piece of the message being sent
69 * @param isLast
70 * true if this is the last piece of the partial bytes
71 * @throws IOException
72 * if unable to send the partial bytes
73 */
74 void sendPartialBytes(ByteBuffer fragment, boolean isLast) throws IOException;
75
76 /**
77 * Send a text message in pieces, blocking until all of the message has been transmitted. The runtime reads the
78 * message in order. Non-final pieces are sent
79 * with isLast set to false. The final piece must be sent with isLast set to true.
80 *
81 * @param fragment
82 * the piece of the message being sent
83 * @param isLast
84 * true if this is the last piece of the partial bytes
85 * @throws IOException
86 * if unable to send the partial bytes
87 */
88 void sendPartialString(String fragment, boolean isLast) throws IOException;
89
90 /**
91 * Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message
92 * may be picked up using the
93 * MessageHandler.Pong handler.
94 *
95 * @param applicationData
96 * the data to be carried in the ping request
97 * @throws IOException
98 * if unable to send the ping
99 */
100 void sendPing(ByteBuffer applicationData) throws IOException;
101
102 /**
103 * Allows the developer to send an unsolicited Pong message containing the given application data in order to serve
104 * as a unidirectional heartbeat for the
105 * session.
106 *
107 * @param applicationData
108 * the application data to be carried in the pong response.
109 * @throws IOException
110 * if unable to send the pong
111 */
112 void sendPong(ByteBuffer applicationData) throws IOException;
113
114 /**
115 * Send a text message, blocking until all bytes of the message has been transmitted.
116 * <p>
117 * Note: this is a blocking call
118 *
119 * @param text
120 * the message to be sent
121 * @throws IOException
122 * if unable to send the text message
123 */
124 void sendString(String text) throws IOException;
125
126 /**
127 * Initiates the asynchronous transmission of a text message. This method may return before the message is
128 * transmitted. Developers may use the returned
129 * Future object to track progress of the transmission.
130 *
131 * @param text
132 * the text being sent
133 * @return the Future object representing the send operation.
134 */
135 Future<Void> sendStringByFuture(String text);
136
137 /**
138 * Initiates the asynchronous transmission of a text message. This method may return before the message is
139 * transmitted. Developers may provide a callback to
140 * be notified when the message has been transmitted or resulted in an error.
141 *
142 * @param text
143 * the text being sent
144 * @param callback
145 * callback to notify of success or failure of the write operation
146 */
147 void sendString(String text, WriteCallback callback);
148
149 /**
150 * @return the batch mode with which messages are sent.
151 * @see #flush()
152 */
153 BatchMode getBatchMode();
154
155 /**
156 * Set the batch mode with which messages are sent.
157 *
158 * @param mode
159 * the batch mode to use
160 * @see #flush()
161 */
162 void setBatchMode(BatchMode mode);
163
164 /**
165 * Flushes messages that may have been batched by the implementation.
166 *
167 * @throws IOException
168 * if the flush fails
169 * @see #getBatchMode()
170 */
171 void flush() throws IOException;
172 }