1 //
2 // ========================================================================
3 // Copyright (c) 1995-2014 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 */
35 void sendBytes(ByteBuffer data) throws IOException;
36
37 /**
38 * Initiates the asynchronous transmission of a binary message. This method returns before the message is transmitted. Developers may use the returned
39 * Future object to track progress of the transmission.
40 *
41 * @param data
42 * the data being sent
43 * @return the Future object representing the send operation.
44 */
45 Future<Void> sendBytesByFuture(ByteBuffer data);
46
47 /**
48 * Initiates the asynchronous transmission of a binary message. This method returns before the message is transmitted. Developers may provide a callback to
49 * be notified when the message has been transmitted or resulted in an error.
50 *
51 * @param data
52 * the data being sent
53 * @param callback
54 * callback to notify of success or failure of the write operation
55 */
56 void sendBytes(ByteBuffer data, WriteCallback callback);
57
58 /**
59 * Send a binary message in pieces, blocking until all of the message has been transmitted. The runtime reads the message in order. Non-final pieces are
60 * sent with isLast set to false. The final piece must be sent with isLast set to true.
61 *
62 * @param fragment
63 * the piece of the message being sent
64 */
65 void sendPartialBytes(ByteBuffer fragment, boolean isLast) throws IOException;
66
67 /**
68 * Send a text message in pieces, blocking until all of the message has been transmitted. The runtime reads the message in order. Non-final pieces are sent
69 * with isLast set to false. The final piece must be sent with isLast set to true.
70 *
71 * @param fragment
72 * the piece of the message being sent
73 */
74 void sendPartialString(String fragment, boolean isLast) throws IOException;
75
76 /**
77 * Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message may be picked up using the
78 * MessageHandler.Pong handler.
79 *
80 * @param applicationData
81 * the data to be carried in the ping request
82 */
83 void sendPing(ByteBuffer applicationData) throws IOException;
84
85 /**
86 * Allows the developer to send an unsolicited Pong message containing the given application data in order to serve as a unidirectional heartbeat for the
87 * session.
88 *
89 * @param applicationData
90 * the application data to be carried in the pong response.
91 */
92 void sendPong(ByteBuffer applicationData) throws IOException;
93
94 /**
95 * Send a text message, blocking until all bytes of the message has been transmitted.
96 * <p>
97 * Note: this is a blocking call
98 *
99 * @param text
100 * the message to be sent
101 */
102 void sendString(String text) throws IOException;
103
104 /**
105 * Initiates the asynchronous transmission of a text message. This method may return before the message is transmitted. Developers may use the returned
106 * Future object to track progress of the transmission.
107 *
108 * @param text
109 * the text being sent
110 * @return the Future object representing the send operation.
111 */
112 Future<Void> sendStringByFuture(String text);
113
114 /**
115 * Initiates the asynchronous transmission of a text message. This method may return before the message is transmitted. Developers may provide a callback to
116 * be notified when the message has been transmitted or resulted in an error.
117 *
118 * @param text
119 * the text being sent
120 * @param callback
121 * callback to notify of success or failure of the write operation
122 */
123 void sendString(String text, WriteCallback callback);
124
125 /**
126 * @return the batch mode with which messages are sent.
127 * @see #flush()
128 */
129 BatchMode getBatchMode();
130
131 /**
132 * Flushes messages that may have been batched by the implementation.
133 * @throws IOException if the flush fails
134 * @see #getBatchMode()
135 */
136 void flush() throws IOException;
137 }