javax.websocket
Interface Session

All Superinterfaces:

Closeable

public interface Session
extends Closeable

A Web Socket session represents a conversation between two web socket endpoints. As soon as the websocket handshake completes successfully, the web socket implementation provides the endpoint an open websocket session. The endpoint can then register interest in incoming messages that are part of this newly created session by providing a MessageHandler to the session, and can send messages to the other end of the conversation by means of the RemoteEndpoint object obtained from this session.

Once the session is closed, it is no longer valid for use by applications. Calling any of its methods once the session has been closed will result in an IllegalStateException being thrown. Developers should retrieve any information from the session during the Endpoint.onClose(javax.websocket.Session, javax.websocket.CloseReason) method.

Since:

DRAFT 001

Author:

dannycoward

Method Summary

void	addMessageHandler(MessageHandler handler) Register to handle to incoming messages in this conversation.
void	close() Close the current conversation with a normal status code and no reason phrase.
void	close(CloseReason closeReason) Close the current conversation, giving a reason for the closure.
WebSocketContainer	getContainer() Return the container that this session is part of.
String	getId() Returns a string containing the unique identifier assigned to this session.
int	getMaxBinaryMessageBufferSize() The maximum length of incoming binary messages that this Session can buffer.
int	getMaxTextMessageBufferSize() The maximum length of incoming text messages that this Session can buffer.
Set<MessageHandler>	getMessageHandlers() Return an unmodifiable copy of the set of MessageHandlers for this Session.
List<Extension>	getNegotiatedExtensions() Return the list of extensions currently in use for this conversation.
String	getNegotiatedSubprotocol() Return the sub protocol agreed during the websocket handshake for this conversation.
Set<Session>	getOpenSessions() Return a copy of the Set of all the open web socket sessions that represent connections to the same endpoint to which this session represents a connection.
Map<String,String>	getPathParameters() Return a map of the path parameter names and values used associated with the request this session was opened under.
String	getProtocolVersion() Returns the version of the websocket protocol currently being used.
String	getQueryString() Return the query string associated with the request this session was opened under.
RemoteEndpoint	getRemote() Return a reference to the RemoteEndpoint object representing the other end of this conversation.
Map<String,List<String>>	getRequestParameterMap() Return the request parameters associated with the request this session was opened under.
URI	getRequestURI() Return the URI under which this session was opened.
long	getTimeout() Return the number of milliseconds before this conversation may be closed by the container if it is inactive, ie no messages are either sent or received in that time.
Principal	getUserPrincipal() Return the authenticated user for this Session or null if no user is authenticated for this session.
Map<String,Object>	getUserProperties() While the session is open, this method returns a Map that the developer may use to store application specific information relating to this session instance.
boolean	isOpen() Return true if and only if the underlying socket is open.
boolean	isSecure() Return true if and only if the underlying socket is using a secure transport.
void	removeMessageHandler(MessageHandler handler) Remove the given MessageHandler from the set belonging to this session.
void	setMaxBinaryMessageBufferSize(int length) Sets the maximum length of incoming binary messages that this Session can buffer.
void	setMaxTextMessageBufferSize(int length) Sets the maximum length of incoming text messages that this Session can buffer.
void	setTimeout(long milliseconds) Set the non-zero number of milliseconds before this conversation will be closed by the container if it is inactive, ie no messages are either sent or received.

Method Detail

getContainer

WebSocketContainer getContainer()

Return the container that this session is part of.

Returns:

the container.

addMessageHandler

void addMessageHandler(MessageHandler handler)
                       throws IllegalStateException

Register to handle to incoming messages in this conversation. A maximum of one message handler per native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum of one message handler to handle incoming text messages a maximum of one message handler for handling incoming binary messages, and a maximum of one for handling incoming pong messages. For further details of which message handlers handle which of the native websocket message types please see MessageHandler.Basic and MessageHandler.Async. Adding more than one of any one type will result in a runtime exception.

Parameters:

handler - the MessageHandler to be added.

Throws:

IllegalStateException - if there is already a MessageHandler registered for the same native websocket message type as this handler.

getMessageHandlers

Set<MessageHandler> getMessageHandlers()

Return an unmodifiable copy of the set of MessageHandlers for this Session.

Returns:

the set of message handlers.

removeMessageHandler

void removeMessageHandler(MessageHandler handler)

Remove the given MessageHandler from the set belonging to this session. This method may block if the given handler is processing a message until it is no longer in use.

Parameters:

handler - the handler to be removed.

getProtocolVersion

String getProtocolVersion()

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 handshake. i.e. "13".

Returns:

the protocol version.

getNegotiatedSubprotocol

String getNegotiatedSubprotocol()

Return the sub protocol agreed during the websocket handshake for this conversation.

Returns:

the negotiated subprotocol.

getNegotiatedExtensions

List<Extension> getNegotiatedExtensions()

Return the list of extensions currently in use for this conversation.

Returns:

the negotiated extensions.

isSecure

boolean isSecure()

Return true if and only if the underlying socket is using a secure transport.

Returns:

whether its using a secure transport.

isOpen

boolean isOpen()

Return true if and only if the underlying socket is open.

Returns:

whether the session is active.

getTimeout

long getTimeout()

Return the number of milliseconds before this conversation may be closed by the container if it is inactive, ie no messages are either sent or received in that time.

Returns:

the timeout in milliseconds.

setTimeout

void setTimeout(long milliseconds)

Set the non-zero number of milliseconds before this conversation will be closed by the container if it is inactive, ie no messages are either sent or received. If the value passed is 0 or negative, this indicates the session will never timeout due to inactivity.

Parameters:

milliseconds - the number of milliseconds.

setMaxBinaryMessageBufferSize

void setMaxBinaryMessageBufferSize(int length)

Sets the maximum length of incoming binary messages that this Session can buffer.

Parameters:

length - the maximum length.

getMaxBinaryMessageBufferSize

int getMaxBinaryMessageBufferSize()

The maximum length of incoming binary messages that this Session can buffer.

Returns:

the message size.

setMaxTextMessageBufferSize

void setMaxTextMessageBufferSize(int length)

Sets the maximum length of incoming text messages that this Session can buffer.

Parameters:

length - the maximum length.

getMaxTextMessageBufferSize

int getMaxTextMessageBufferSize()

The maximum length of incoming text messages that this Session can buffer.

Returns:

the message size.

getRemote

RemoteEndpoint getRemote()

Return a reference to the RemoteEndpoint object representing the other end of this conversation.

Returns:

the remote endpoint.

getId

String getId()

Returns a string containing the unique identifier assigned to this session. The identifier is assigned by the web socket implementation and is implementation dependent.

Returns:

the unique identifier for this session instance.

close

void close()
           throws IOException

Close the current conversation with a normal status code and no reason phrase.

Specified by:

close in interface Closeable

Throws:

IOException - if there was a connection error closing the connection.

close

void close(CloseReason closeReason)
           throws IOException

Close the current conversation, giving a reason for the closure. Note the websocket spec defines the acceptable uses of status codes and reason phrases. If the application cannot determine a suitable close code to use for the closeReason, it is recommended to use CloseReason.CloseCodes.NO_STATUS_CODE.

Parameters:

closeReason - the reason for the closure.

Throws:

IOException - if there was a connection error closing the connection

getRequestURI

URI getRequestURI()

Return the URI under which this session was opened.

Returns:

the request URI.

getRequestParameterMap

Map<String,List<String>> getRequestParameterMap()

Return the request parameters associated with the request this session was opened under.

Returns:

the unmodifiable map of the request parameters.

getQueryString

String getQueryString()

Return the query string associated with the request this session was opened under.

Returns:

the query string

getPathParameters

Map<String,String> getPathParameters()

Return a map of the path parameter names and values used associated with the request this session was opened under.

Returns:

the unmodifiable map of path parameters. The key of the map is the parameter name, the values in the map are the parameter values.

getUserProperties

Map<String,Object> getUserProperties()

While the session is open, this method returns a Map that the developer may use to store application specific information relating to this session instance. The developer may retrieve information from this Map at any time between the opening of the session and during the onClose() method. But outside that time, any information stored using this Map may no longer be kept by the container. Web socket applications running on distributed implementations of the web container should make any application specific objects stored here java.io.Serializable, or the object may not be recreated after a failover.

Returns:

an editable Map of application data.

getUserPrincipal

Principal getUserPrincipal()

Return the authenticated user for this Session or null if no user is authenticated for this session.

Returns:

the user principal.

getOpenSessions

Set<Session> getOpenSessions()

Return a copy of the Set of all the open web socket sessions that represent connections to the same endpoint to which this session represents a connection. The Set includes the session this method is called on. These sessions may not still be open at any point after the return of this method. For example, iterating over the set at a later time may yield one or more closed sessions. Developers should use session.isOpen() to check.

Returns:

the set of sessions, open at the time of return.