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