1 //
2 // ========================================================================
3 // Copyright (c) 1995-2015 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.Closeable;
22 import java.io.IOException;
23 import java.net.InetSocketAddress;
24
25 import org.eclipse.jetty.websocket.api.annotations.OnWebSocketClose;
26
27 /**
28 * Session represents an active link of communications with a Remote WebSocket Endpoint.
29 */
30 public interface Session extends Closeable
31 {
32 /**
33 * Request a close of the current conversation with a normal status code and no reason phrase.
34 * <p>
35 * This will enqueue a graceful close to the remote endpoint.
36 *
37 * @see #close(CloseStatus)
38 * @see #close(int, String)
39 * @see #disconnect()
40 */
41 @Override
42 void close();
43
44 /**
45 * Request Close the current conversation, giving a reason for the closure. Note the websocket spec defines the acceptable uses of status codes and reason
46 * phrases.
47 * <p>
48 * This will enqueue a graceful close to the remote endpoint.
49 *
50 * @param closeStatus
51 * the reason for the closure
52 *
53 * @see #close()
54 * @see #close(int, String)
55 * @see #disconnect()
56 */
57 void close(CloseStatus closeStatus);
58
59 /**
60 * Send a websocket Close frame, with status code.
61 * <p>
62 * This will enqueue a graceful close to the remote endpoint.
63 *
64 * @param statusCode
65 * the status code
66 * @param reason
67 * the (optional) reason. (can be null for no reason)
68 * @see StatusCode
69 *
70 * @see #close()
71 * @see #close(CloseStatus)
72 * @see #disconnect()
73 */
74 void close(int statusCode, String reason);
75
76 /**
77 * Issue a harsh disconnect of the underlying connection.
78 * <p>
79 * This will terminate the connection, without sending a websocket close frame.
80 * <p>
81 * Once called, any read/write activity on the websocket from this point will be indeterminate.
82 * <p>
83 * Once the underlying connection has been determined to be closed, the various onClose() events (either
84 * {@link WebSocketListener#onWebSocketClose(int, String)} or {@link OnWebSocketClose}) will be called on your
85 * websocket.
86 *
87 * @throws IOException
88 * if unable to disconnect
89 *
90 * @see #close()
91 * @see #close(CloseStatus)
92 * @see #close(int, String)
93 * @see #disconnect()
94 */
95 void disconnect() throws IOException;
96
97 /**
98 * Return the number of milliseconds before this conversation will be closed by the container if it is inactive, ie no messages are either sent or received
99 * in that time.
100 *
101 * @return the timeout in milliseconds.
102 */
103 long getIdleTimeout();
104
105 /**
106 * Get the address of the local side.
107 *
108 * @return the local side address
109 */
110 public InetSocketAddress getLocalAddress();
111
112 /**
113 * Access the (now read-only) {@link WebSocketPolicy} in use for this connection.
114 *
115 * @return the policy in use
116 */
117 WebSocketPolicy getPolicy();
118
119 /**
120 * Returns the version of the websocket protocol currently being used. This is taken as the value of the Sec-WebSocket-Version header used in the opening
121 * handshake. i.e. "13".
122 *
123 * @return the protocol version
124 */
125 String getProtocolVersion();
126
127 /**
128 * Return a reference to the RemoteEndpoint object representing the other end of this conversation.
129 *
130 * @return the remote endpoint
131 */
132 RemoteEndpoint getRemote();
133
134 /**
135 * Get the address of the remote side.
136 *
137 * @return the remote side address
138 */
139 public InetSocketAddress getRemoteAddress();
140
141 /**
142 * Get the UpgradeRequest used to create this session
143 *
144 * @return the UpgradeRequest used to create this session
145 */
146 UpgradeRequest getUpgradeRequest();
147
148 /**
149 * Get the UpgradeResponse used to create this session
150 *
151 * @return the UpgradeResponse used to create this session
152 */
153 UpgradeResponse getUpgradeResponse();
154
155 /**
156 * Return true if and only if the underlying socket is open.
157 *
158 * @return whether the session is open
159 */
160 abstract boolean isOpen();
161
162 /**
163 * Return true if and only if the underlying socket is using a secure transport.
164 *
165 * @return whether its using a secure transport
166 */
167 boolean isSecure();
168
169 /**
170 * Set the number of milliseconds before this conversation will be closed by the container if it is inactive, ie no messages are either sent or received.
171 *
172 * @param ms
173 * the number of milliseconds.
174 */
175 void setIdleTimeout(long ms);
176
177 /**
178 * Suspend a the incoming read events on the connection.
179 *
180 * @return the suspend token suitable for resuming the reading of data on the connection.
181 */
182 SuspendToken suspend();
183 }