javax.websocket

Interface Session

public interface Session

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 active websocket session. The endpoint can then register interest in incoming messages that are part of this newly created conversation 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.

Since:

DRAFT 001

Author:

dannycoward

Method Summary

Methods

Modifier and Type	Method and Description
void	addMessageHandler(MessageHandler listener) 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 closeStatus) Close the current conversation, giving a reason for the closure.
ClientContainer	getContainer() Return the container that this session is part of.
long	getInactiveTime() Return the number of seconds since the underlying connection had any activity.
long	getMaximumMessageSize() The maximum total length of messages, text or binary, that this Session can handle.
Set<MessageHandler>	getMessageHandlers() Return an unmodifiable copy of the set of MessageHandlers for this Session.
List<String>	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.
Map<String,String>	getPathParameters() Return a map of the path parameter names and values used if the server endpoint was deployed with a URI-template and the client connected with a particular matching URL.
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,String[]>	getRequestParameterMap() Return the request parameters associated with the request this session was opened under.
URI	getRequestURI() Return the URI that this session was opened under.
long	getTimeout() 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 in that time.
boolean	isActive() 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 listener) Remove the given MessageHandler from the set belonging to this session.
void	setEncoders(List<Encoder> encoders) Sets the list of encoders to be used in this session in order of preference.
void	setMaximumMessageSize(long length) Sets the maximum total length of messages, text or binary, that this Session can handle.
void	setTimeout(long seconds) 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.

Method Detail

getContainer

ClientContainer getContainer()

Return the container that this session is part of.

Returns:

the container

setEncoders

void setEncoders(List<Encoder> encoders)

Sets the list of encoders to be used in this session in order of preference. The first element in the list that matches for a given type will be used rather than a later element in the list that matches for a given type.

Parameters:

encoders - the list of encoders.

addMessageHandler

void addMessageHandler(MessageHandler listener)

Register to handle to incoming messages in this conversation.

Parameters:

listener - the MessageHandler to be added.

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 listener)

Remove the given MessageHandler from the set belonging to this session.

Parameters:

listener - the handler to be removed. TBD Threading issues wrt handler invocations vs removal

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<String> 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.

getInactiveTime

long getInactiveTime()

Return the number of seconds since the underlying connection had any activity.

Returns:

the inactive time.

isActive

boolean isActive()

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 will 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 seconds)

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.

Parameters:

seconds - the number of milliseconds.

setMaximumMessageSize

void setMaximumMessageSize(long length)

Sets the maximum total length of messages, text or binary, that this Session can handle.

Parameters:

length - the maximum length

getMaximumMessageSize

long getMaximumMessageSize()

The maximum total length of messages, text or binary, that this Session can handle.

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.

close

void close()
           throws IOException

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

Throws:

IOException

close

void close(CloseReason closeStatus)
           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.

Parameters:

closeStatus - the reason for the closure.

Throws:

IOException

getRequestURI

URI getRequestURI()

Return the URI that this session was opened under.

Returns:

the request URI.

getRequestParameterMap

Map<String,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:

getPathParameters

Map<String,String> getPathParameters()

Return a map of the path parameter names and values used if the server endpoint was deployed with a URI-template and the client connected with a particular matching URL.

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.