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 }