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.net.InetSocketAddress;
23 import java.nio.ByteBuffer;
24 import java.util.concurrent.Future;
25
26 public interface RemoteEndpoint
27 {
28 /**
29 * Send a binary message, returning when all bytes of the message has been transmitted.
30 * <p>
31 * Note: this is a blocking call
32 *
33 * @param data
34 * the message to be sent
35 * @throws IOException
36 * if unable to send the bytes
37 */
38 void sendBytes(ByteBuffer data) throws IOException;
39
40 /**
41 * Initiates the asynchronous transmission of a binary message. This method returns before the message is
42 * transmitted. Developers may use the returned
43 * Future object to track progress of the transmission.
44 *
45 * @param data
46 * the data being sent
47 * @return the Future object representing the send operation.
48 */
49 Future<Void> sendBytesByFuture(ByteBuffer data);
50
51 /**
52 * Initiates the asynchronous transmission of a binary message. This method returns before the message is
53 * transmitted. Developers may provide a callback to
54 * be notified when the message has been transmitted or resulted in an error.
55 *
56 * @param data
57 * the data being sent
58 * @param callback
59 * callback to notify of success or failure of the write operation
60 */
61 void sendBytes(ByteBuffer data, WriteCallback callback);
62
63 /**
64 * Send a binary message in pieces, blocking until all of the message has been transmitted. The runtime reads the
65 * message in order. Non-final pieces are
66 * sent with isLast set to false. The final piece must be sent with isLast set to true.
67 *
68 * @param fragment
69 * the piece of the message being sent
70 * @param isLast
71 * true if this is the last piece of the partial bytes
72 * @throws IOException
73 * if unable to send the partial bytes
74 */
75 void sendPartialBytes(ByteBuffer fragment, boolean isLast) throws IOException;
76
77 /**
78 * Send a text message in pieces, blocking until all of the message has been transmitted. The runtime reads the
79 * message in order. Non-final pieces are sent
80 * with isLast set to false. The final piece must be sent with isLast set to true.
81 *
82 * @param fragment
83 * the piece of the message being sent
84 * @param isLast
85 * true if this is the last piece of the partial bytes
86 * @throws IOException
87 * if unable to send the partial bytes
88 */
89 void sendPartialString(String fragment, boolean isLast) throws IOException;
90
91 /**
92 * Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message
93 * may be picked up using the
94 * MessageHandler.Pong handler.
95 *
96 * @param applicationData
97 * the data to be carried in the ping request
98 * @throws IOException
99 * if unable to send the ping
100 */
101 void sendPing(ByteBuffer applicationData) throws IOException;
102
103 /**
104 * Allows the developer to send an unsolicited Pong message containing the given application data in order to serve
105 * as a unidirectional heartbeat for the
106 * session.
107 *
108 * @param applicationData
109 * the application data to be carried in the pong response.
110 * @throws IOException
111 * if unable to send the pong
112 */
113 void sendPong(ByteBuffer applicationData) throws IOException;
114
115 /**
116 * Send a text message, blocking until all bytes of the message has been transmitted.
117 * <p>
118 * Note: this is a blocking call
119 *
120 * @param text
121 * the message to be sent
122 * @throws IOException
123 * if unable to send the text message
124 */
125 void sendString(String text) throws IOException;
126
127 /**
128 * Initiates the asynchronous transmission of a text message. This method may return before the message is
129 * transmitted. Developers may use the returned
130 * Future object to track progress of the transmission.
131 *
132 * @param text
133 * the text being sent
134 * @return the Future object representing the send operation.
135 */
136 Future<Void> sendStringByFuture(String text);
137
138 /**
139 * Initiates the asynchronous transmission of a text message. This method may return before the message is
140 * transmitted. Developers may provide a callback to
141 * be notified when the message has been transmitted or resulted in an error.
142 *
143 * @param text
144 * the text being sent
145 * @param callback
146 * callback to notify of success or failure of the write operation
147 */
148 void sendString(String text, WriteCallback callback);
149
150 /**
151 * @return the batch mode with which messages are sent.
152 * @see #flush()
153 */
154 BatchMode getBatchMode();
155
156 /**
157 * Set the batch mode with which messages are sent.
158 *
159 * @param mode
160 * the batch mode to use
161 * @see #flush()
162 */
163 void setBatchMode(BatchMode mode);
164
165 /**
166 * Get the InetSocketAddress for the established connection.
167 *
168 * @return the InetSocketAddress for the established connection. (or null, if the connection is no longer established)
169 */
170 InetSocketAddress getInetSocketAddress();
171
172 /**
173 * Flushes messages that may have been batched by the implementation.
174 *
175 * @throws IOException
176 * if the flush fails
177 * @see #getBatchMode()
178 */
179 void flush() throws IOException;
180 }