1 //
2 // ========================================================================
3 // Copyright (c) 1995-2013 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 provide a callback to
39 * be notified when the message has been transmitted, or may use the returned Future object to track progress of the transmission. Errors in transmission
40 * are given to the developer in the WriteResult object in either case.
41 *
42 * @param data
43 * the data being sent
44 * @param completion
45 * handler that will be notified of progress
46 * @return the Future object representing the send operation.
47 */
48 Future<Void> sendBytesByFuture(ByteBuffer data);
49
50 /**
51 * 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
52 * sent with isLast set to false. The final piece must be sent with isLast set to true.
53 *
54 * @param fragment
55 * the piece of the message being sent
56 */
57 void sendPartialBytes(ByteBuffer fragment, boolean isLast) throws IOException;
58
59 /**
60 * 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
61 * with isLast set to false. The final piece must be sent with isLast set to true.
62 *
63 * @param fragment
64 * the piece of the message being sent
65 */
66 void sendPartialString(String fragment, boolean isLast) throws IOException;
67
68 /**
69 * Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message may be picked up using the
70 * MessageHandler.Pong handler.
71 *
72 * @param applicationData
73 * the data to be carried in the ping request
74 */
75 void sendPing(ByteBuffer applicationData) throws IOException;
76
77 /**
78 * Allows the developer to send an unsolicited Pong message containing the given application data in order to serve as a unidirectional heartbeat for the
79 * session.
80 *
81 * @param applicationData
82 * the application data to be carried in the pong response.
83 */
84 void sendPong(ByteBuffer applicationData) throws IOException;
85
86 /**
87 * Send a text message, blocking until all bytes of the message has been transmitted.
88 * <p>
89 * Note: this is a blocking call
90 *
91 * @param text
92 * the message to be sent
93 */
94 void sendString(String text) throws IOException;
95
96 /**
97 * Initiates the asynchronous transmission of a text message. This method returns before the message is transmitted. Developers may provide a callback to be
98 * notified when the message has been transmitted, or may use the returned Future object to track progress of the transmission. Errors in transmission are
99 * given to the developer in the WriteResult object in either case.
100 *
101 * @param text
102 * the text being sent
103 * @param completion
104 * the handler which will be notified of progress
105 * @return the Future object representing the send operation.
106 */
107 Future<Void> sendStringByFuture(String text);
108 }