1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package javax.websocket; 18 19 import java.io.Closeable; 20 import java.io.IOException; 21 import java.net.URI; 22 import java.security.Principal; 23 import java.util.List; 24 import java.util.Map; 25 import java.util.Set; 26 27 public interface Session extends Closeable { 28 29 /** 30 * Get the container that created this session. 31 * @return the container that created this session. 32 */ getContainer()33 WebSocketContainer getContainer(); 34 35 /** 36 * Registers a {@link MessageHandler} for incoming messages. Only one 37 * {@link MessageHandler} may be registered for each message type (text, 38 * binary, pong). The message type will be derived at runtime from the 39 * provided {@link MessageHandler} instance. It is not always possible to do 40 * this so it is better to use 41 * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Partial)} 42 * or 43 * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Whole)}. 44 * 45 * @param handler The message handler for a incoming message 46 * 47 * @throws IllegalStateException If a message handler has already been 48 * registered for the associated message type 49 */ addMessageHandler(MessageHandler handler)50 void addMessageHandler(MessageHandler handler) throws IllegalStateException; 51 getMessageHandlers()52 Set<MessageHandler> getMessageHandlers(); 53 removeMessageHandler(MessageHandler listener)54 void removeMessageHandler(MessageHandler listener); 55 getProtocolVersion()56 String getProtocolVersion(); 57 getNegotiatedSubprotocol()58 String getNegotiatedSubprotocol(); 59 getNegotiatedExtensions()60 List<Extension> getNegotiatedExtensions(); 61 isSecure()62 boolean isSecure(); 63 isOpen()64 boolean isOpen(); 65 66 /** 67 * Get the idle timeout for this session. 68 * @return The current idle timeout for this session in milliseconds. Zero 69 * or negative values indicate an infinite timeout. 70 */ getMaxIdleTimeout()71 long getMaxIdleTimeout(); 72 73 /** 74 * Set the idle timeout for this session. 75 * @param timeout The new idle timeout for this session in milliseconds. 76 * Zero or negative values indicate an infinite timeout. 77 */ setMaxIdleTimeout(long timeout)78 void setMaxIdleTimeout(long timeout); 79 80 /** 81 * Set the current maximum buffer size for binary messages. 82 * @param max The new maximum buffer size in bytes 83 */ setMaxBinaryMessageBufferSize(int max)84 void setMaxBinaryMessageBufferSize(int max); 85 86 /** 87 * Get the current maximum buffer size for binary messages. 88 * @return The current maximum buffer size in bytes 89 */ getMaxBinaryMessageBufferSize()90 int getMaxBinaryMessageBufferSize(); 91 92 /** 93 * Set the maximum buffer size for text messages. 94 * @param max The new maximum buffer size in characters. 95 */ setMaxTextMessageBufferSize(int max)96 void setMaxTextMessageBufferSize(int max); 97 98 /** 99 * Get the maximum buffer size for text messages. 100 * @return The maximum buffer size in characters. 101 */ getMaxTextMessageBufferSize()102 int getMaxTextMessageBufferSize(); 103 getAsyncRemote()104 RemoteEndpoint.Async getAsyncRemote(); 105 getBasicRemote()106 RemoteEndpoint.Basic getBasicRemote(); 107 108 /** 109 * Provides a unique identifier for the session. This identifier should not 110 * be relied upon to be generated from a secure random source. 111 * @return A unique identifier for the session. 112 */ getId()113 String getId(); 114 115 /** 116 * Close the connection to the remote end point using the code 117 * {@link javax.websocket.CloseReason.CloseCodes#NORMAL_CLOSURE} and an 118 * empty reason phrase. 119 * 120 * @throws IOException if an I/O error occurs while the WebSocket session is 121 * being closed. 122 */ 123 @Override close()124 void close() throws IOException; 125 126 127 /** 128 * Close the connection to the remote end point using the specified code 129 * and reason phrase. 130 * @param closeReason The reason the WebSocket session is being closed. 131 * 132 * @throws IOException if an I/O error occurs while the WebSocket session is 133 * being closed. 134 */ close(CloseReason closeReason)135 void close(CloseReason closeReason) throws IOException; 136 getRequestURI()137 URI getRequestURI(); 138 getRequestParameterMap()139 Map<String, List<String>> getRequestParameterMap(); 140 getQueryString()141 String getQueryString(); 142 getPathParameters()143 Map<String,String> getPathParameters(); 144 getUserProperties()145 Map<String,Object> getUserProperties(); 146 getUserPrincipal()147 Principal getUserPrincipal(); 148 149 /** 150 * Obtain the set of open sessions associated with the same local endpoint 151 * as this session. 152 * 153 * @return The set of currently open sessions for the local endpoint that 154 * this session is associated with. 155 */ getOpenSessions()156 Set<Session> getOpenSessions(); 157 158 /** 159 * Registers a {@link MessageHandler} for partial incoming messages. Only 160 * one {@link MessageHandler} may be registered for each message type (text 161 * or binary, pong messages are never presented as partial messages). 162 * 163 * @param <T> The type of message that the given handler is intended 164 * for 165 * @param clazz The Class that implements T 166 * @param handler The message handler for a incoming message 167 * 168 * @throws IllegalStateException If a message handler has already been 169 * registered for the associated message type 170 * 171 * @since WebSocket 1.1 172 */ addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler)173 <T> void addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler) 174 throws IllegalStateException; 175 176 /** 177 * Registers a {@link MessageHandler} for whole incoming messages. Only 178 * one {@link MessageHandler} may be registered for each message type (text, 179 * binary, pong). 180 * 181 * @param <T> The type of message that the given handler is intended 182 * for 183 * @param clazz The Class that implements T 184 * @param handler The message handler for a incoming message 185 * 186 * @throws IllegalStateException If a message handler has already been 187 * registered for the associated message type 188 * 189 * @since WebSocket 1.1 190 */ addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler)191 <T> void addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler) 192 throws IllegalStateException; 193 } 194