TyrusSession (Tyrus 1.13.1 API)

java.lang.Object
- org.glassfish.tyrus.core.TyrusSession

All Implemented Interfaces:

Closeable, AutoCloseable, Session, DistributedSession
```
public class TyrusSession
extends Object
implements Session, DistributedSession
```
Implementation of the Session.

Author:

Danny Coward (danny.coward at oracle.com), Stepan Kopriva (stepan.kopriva at oracle.com), Martin Matula (martin.matula at oracle.com), Pavel Bucek (pavel.bucek at oracle.com)

Method Summary

Methods
Modifier and Type	Method and Description
`<T> void`	`addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler)` Register to handle to incoming messages in this conversation.
`<T> void`	`addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler)` Register to handle to incoming messages in this conversation.
`void`	`addMessageHandler(MessageHandler handler)` Deprecated. please use `addMessageHandler(Class, javax.websocket.MessageHandler.Whole)` or `addMessageHandler(Class, javax.websocket.MessageHandler.Partial)`
`Map<Session,Future<?>>`	`broadcast(ByteBuffer message)` Broadcasts binary message to all connected clients, including remote sessions (if any).
`Map<Session,Future<?>>`	`broadcast(String message)` Broadcasts text message to all connected clients.
`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.
`Set<DistributedSession>`	`getAllSessions()` Get set of all sessions opened to the same endpoint.
`RemoteEndpoint.Async`	`getAsyncRemote()` Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send messages asynchronously to the peer.
`RemoteEndpoint.Basic`	`getBasicRemote()` Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send messages synchronously to the peer.
`WebSocketContainer`	`getContainer()` Return the container that this session is part of.
`Map<String,Object>`	`getDistributedProperties()` Get distributed properties.
`long`	`getHeartbeatInterval()` Return an interval in milliseconds between scheduled periodic Pong messages.
`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.
`long`	`getMaxIdleTimeout()` Return the number of milliseconds before this conversation may be closed by the container if it is inactive, i.e.
`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.
`String`	`getRemoteAddr()` Get the Internet Protocol (IP) address of the client or last proxy that sent the request.
`Set<RemoteSession>`	`getRemoteSessions()` Get set of remote sessions.
`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, including the query string if there is one.
`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`	`setHeartbeatInterval(long heartbeatInterval)` Set an interval in milliseconds between scheduled periodic Pong messages.
`void`	`setMaxBinaryMessageBufferSize(int maxBinaryMessageBufferSize)` Sets the maximum length of incoming binary messages that this Session can buffer.
`void`	`setMaxIdleTimeout(long maxIdleTimeout)` Set the non-zero number of milliseconds before this session will be closed by the container if it is inactive, ie no messages are either sent or received.
`void`	`setMaxTextMessageBufferSize(int maxTextMessageBufferSize)` Sets the maximum length of incoming text messages that this Session can buffer.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - getProtocolVersion
```
public String getProtocolVersion()
```
    Description copied from interface: Session
    
    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".
    
    Specified by:
    
    getProtocolVersion in interface Session
    
    Returns:
    the protocol version.
  - getNegotiatedSubprotocol
```
public String getNegotiatedSubprotocol()
```
    Description copied from interface: Session
    
    Return the sub protocol agreed during the websocket handshake for this conversation.
    
    Specified by:
    
    getNegotiatedSubprotocol in interface Session
    
    Returns:
    the negotiated subprotocol, or the empty string if there isn't one.
  - getAsyncRemote
```
public RemoteEndpoint.Async getAsyncRemote()
```
    Description copied from interface: Session
    
    Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send messages asynchronously to the peer.
    
    Specified by:
    
    getAsyncRemote in interface Session
    
    Returns:
    the remote endpoint.
  - getBasicRemote
```
public RemoteEndpoint.Basic getBasicRemote()
```
    Description copied from interface: Session
    
    Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send messages synchronously to the peer.
    
    Specified by:
    
    getBasicRemote in interface Session
    
    Returns:
    the remote endpoint.
  - isOpen
```
public boolean isOpen()
```
    Description copied from interface: Session
    
    Return true if and only if the underlying socket is open.
    
    Specified by:
    
    isOpen in interface Session
    
    Returns:
    whether the session is active.
  - close
```
public void close()
           throws IOException
```
    Description copied from interface: Session
    
    Close the current conversation with a normal status code and no reason phrase.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Session
    
    Throws:
    
    IOException - if there was a connection error closing the connection.
  - close
```
public void close(CloseReason closeReason)
           throws IOException
```
    Description copied from interface: Session
    
    Close the current conversation, giving a reason for the closure. The close call causes the implementation to attempt notify the client of the close as soon as it can. This may cause the sending of unsent messages immediately prior to the close notification. After the close notification has been sent the implementation notifies the endpoint's onClose method. Note the websocket specification 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.
    
    Specified by:
    
    close in interface Session
    
    Parameters:
    closeReason - the reason for the closure.
    
    Throws:
    
    IOException - if there was a connection error closing the connection
  - getMaxBinaryMessageBufferSize
```
public int getMaxBinaryMessageBufferSize()
```
    Description copied from interface: Session
    
    The maximum length of incoming binary messages that this Session can buffer. If the implementation receives a binary message that it cannot buffer because it is too large, it must close the session with a close code of CloseReason.CloseCodes.TOO_BIG.
    
    Specified by:
    
    getMaxBinaryMessageBufferSize in interface Session
    
    Returns:
    the maximum binary message size that can be buffered.
  - setMaxBinaryMessageBufferSize
```
public void setMaxBinaryMessageBufferSize(int maxBinaryMessageBufferSize)
```
    Description copied from interface: Session
    
    Sets the maximum length of incoming binary messages that this Session can buffer.
    
    Specified by:
    
    setMaxBinaryMessageBufferSize in interface Session
    
    Parameters:
    maxBinaryMessageBufferSize - the maximum length.
  - getMaxTextMessageBufferSize
```
public int getMaxTextMessageBufferSize()
```
    Description copied from interface: Session
    
    The maximum length of incoming text messages that this Session can buffer. If the implementation receives a text message that it cannot buffer because it is too large, it must close the session with a close code of CloseReason.CloseCodes.TOO_BIG.
    
    Specified by:
    
    getMaxTextMessageBufferSize in interface Session
    
    Returns:
    the maximum text message size that can be buffered.
  - setMaxTextMessageBufferSize
```
public void setMaxTextMessageBufferSize(int maxTextMessageBufferSize)
```
    Description copied from interface: Session
    
    Sets the maximum length of incoming text messages that this Session can buffer.
    
    Specified by:
    
    setMaxTextMessageBufferSize in interface Session
    
    Parameters:
    maxTextMessageBufferSize - the maximum length.
  - getOpenSessions
```
public Set<Session> getOpenSessions()
```
    Description copied from interface: Session
    
    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.
    
    Specified by:
    
    getOpenSessions in interface Session
    
    Returns:
    the set of sessions, open at the time of return.
  - getRemoteSessions
```
public Set<RemoteSession> getRemoteSessions()
```
    Get set of remote sessions.
    Remote sessions are websocket sessions which are bound to another node in the cluster.
    
    Returns:
    set of remote sessions or empty set, when not running in cluster environment.
  - getAllSessions
```
public Set<DistributedSession> getAllSessions()
```
    Get set of all sessions opened to the same endpoint.
    Set returned from this method contains all "local" and remote sessions (if any).
    
    Returns:
    set of distributed sessions.
    See Also:
    RemoteSession
  - getNegotiatedExtensions
```
public List<Extension> getNegotiatedExtensions()
```
    Description copied from interface: Session
    
    Return the list of extensions currently in use for this conversation.
    
    Specified by:
    
    getNegotiatedExtensions in interface Session
    
    Returns:
    the negotiated extensions.
  - getMaxIdleTimeout
```
public long getMaxIdleTimeout()
```
    Description copied from interface: Session
    
    Return the number of milliseconds before this conversation may be closed by the container if it is inactive, i.e. no messages are either sent or received in that time.
    
    Specified by:
    
    getMaxIdleTimeout in interface Session
    
    Returns:
    the timeout in milliseconds.
  - setMaxIdleTimeout
```
public void setMaxIdleTimeout(long maxIdleTimeout)
```
    Description copied from interface: Session
    
    Set the non-zero number of milliseconds before this session will be closed by the container if it is inactive, ie no messages are either sent or received. A value that is 0 or negative indicates the session will never timeout due to inactivity.
    
    Specified by:
    
    setMaxIdleTimeout in interface Session
    
    Parameters:
    maxIdleTimeout - the number of milliseconds.
  - isSecure
```
public boolean isSecure()
```
    Description copied from interface: Session
    
    Return true if and only if the underlying socket is using a secure transport.
    
    Specified by:
    
    isSecure in interface Session
    
    Returns:
    whether its using a secure transport.
  - getContainer
```
public WebSocketContainer getContainer()
```
    Description copied from interface: Session
    
    Return the container that this session is part of.
    
    Specified by:
    
    getContainer in interface Session
    
    Returns:
    the container.
  - addMessageHandler
```
public void addMessageHandler(MessageHandler handler)
```
    Deprecated. please use addMessageHandler(Class, javax.websocket.MessageHandler.Whole) or addMessageHandler(Class, javax.websocket.MessageHandler.Partial)
    
    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.Whole and MessageHandler.Partial. Adding more than one of any one type will result in a runtime exception.
    This method is not safe to use unless you are providing an anonymous class derived directly from MessageHandler.Whole or MessageHandler.Partial. In all other cases (Lambda Expressions, more complex inheritance or generic type arrangements), one of the following methods have to be used: Session.addMessageHandler(Class, javax.websocket.MessageHandler.Whole) or Session.addMessageHandler(Class, javax.websocket.MessageHandler.Partial).
    
    Specified by:
    
    addMessageHandler in interface Session
    
    Parameters:
    handler - the MessageHandler to be added.
  - addMessageHandler
```
public <T> void addMessageHandler(Class<T> clazz,
                         MessageHandler.Whole<T> handler)
```
    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.Whole and MessageHandler.Partial. Adding more than one of any one type will result in a runtime exception.
    See Endpoint for a usage example.
    
    Specified by:
    
    addMessageHandler in interface Session
    
    Parameters:
    clazz - type of the message processed by message handler to be registered.
    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.
  - addMessageHandler
```
public <T> void addMessageHandler(Class<T> clazz,
                         MessageHandler.Partial<T> handler)
```
    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.Whole and MessageHandler.Partial. Adding more than one of any one type will result in a runtime exception.
    See Endpoint for a usage example.
    
    Specified by:
    
    addMessageHandler in interface Session
    
    Parameters:
    clazz - type of the message processed by message handler to be registered.
    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
```
public Set<MessageHandler> getMessageHandlers()
```
    Description copied from interface: Session
    
    Return an unmodifiable copy of the set of MessageHandlers for this Session.
    
    Specified by:
    
    getMessageHandlers in interface Session
    
    Returns:
    the set of message handlers.
  - removeMessageHandler
```
public void removeMessageHandler(MessageHandler handler)
```
    Description copied from interface: Session
    
    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.
    
    Specified by:
    
    removeMessageHandler in interface Session
    
    Parameters:
    handler - the handler to be removed.
  - getRequestURI
```
public URI getRequestURI()
```
    Description copied from interface: Session
    
    Return the URI under which this session was opened, including the query string if there is one.
    
    Specified by:
    
    getRequestURI in interface Session
    
    Returns:
    the request URI.
  - getRequestParameterMap
```
public Map<String,List<String>> getRequestParameterMap()
```
    Description copied from interface: Session
    
    Return the request parameters associated with the request this session was opened under.
    
    Specified by:
    
    getRequestParameterMap in interface Session
    
    Returns:
    the unmodifiable map of the request parameters.
  - getPathParameters
```
public Map<String,String> getPathParameters()
```
    Description copied from interface: Session
    
    Return a map of the path parameter names and values used associated with the request this session was opened under.
    
    Specified by:
    
    getPathParameters in interface Session
    
    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
```
public Map<String,Object> getUserProperties()
```
    Description copied from interface: Session
    
    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.
    
    Specified by:
    
    getUserProperties in interface Session
    
    Returns:
    an editable Map of application data.
  - getDistributedProperties
```
public Map<String,Object> getDistributedProperties()
```
    Description copied from interface: DistributedSession
    
    Get distributed properties.
    Values put into this map must be Serializable or serializable by other, implementation-dependent alternative.
    Content of this map is synchronized among all cluster nodes, so putting an entry on any of the nodes will be visible on all other nodes which have reference to current session (in form of TyrusSession or RemoteSession).
    Please note that when not running in the distributed environment, this map behaves similarly to Session.getUserProperties(), so no serialization or deserialization is performed when values are read from or stored to the returned map.
    
    Specified by:
    
    getDistributedProperties in interface DistributedSession
    
    Returns:
    map of distributed properties.
    See Also:
    TyrusSession, RemoteSession
  - getQueryString
```
public String getQueryString()
```
    Description copied from interface: Session
    
    Return the query string associated with the request this session was opened under.
    
    Specified by:
    
    getQueryString in interface Session
    
    Returns:
    the query string
  - getId
```
public String getId()
```
    Description copied from interface: Session
    
    Returns a string containing the unique identifier assigned to this session. The identifier is assigned by the web socket implementation and is implementation dependent.
    
    Specified by:
    
    getId in interface Session
    
    Returns:
    the unique identifier for this session instance.
  - getUserPrincipal
```
public Principal getUserPrincipal()
```
    Description copied from interface: Session
    
    Return the authenticated user for this Session or null if no user is authenticated for this session.
    
    Specified by:
    
    getUserPrincipal in interface Session
    
    Returns:
    the user principal.
  - broadcast
```
public Map<Session,Future<?>> broadcast(String message)
```
    Broadcasts text message to all connected clients.
    The broadcast can be executed in parallel, which can be enabled by setting TyrusWebSocketEngine.PARALLEL_BROADCAST_ENABLED to true in server properties.
    
    Parameters:
    message - message to be broadcasted.
    
    Returns:
    map of local sessions and futures for user to get the information about status of the message.
  - broadcast
```
public Map<Session,Future<?>> broadcast(ByteBuffer message)
```
    Broadcasts binary message to all connected clients, including remote sessions (if any).
    The broadcast can be executed in parallel, which can be enabled by setting TyrusWebSocketEngine.PARALLEL_BROADCAST_ENABLED to true in server properties.
    
    Parameters:
    message - message to be broadcasted.
    
    Returns:
    map of local sessions and futures for user to get the information about status of the message.
  - getHeartbeatInterval
```
public long getHeartbeatInterval()
```
    Return an interval in milliseconds between scheduled periodic Pong messages. A negative value or 0 means that sending of periodic Pong messages is not turned on.
    
    Returns:
    heartbeatInterval interval between periodic pong messages in milliseconds.
  - setHeartbeatInterval
```
public void setHeartbeatInterval(long heartbeatInterval)
```
    Set an interval in milliseconds between scheduled periodic Pong messages. Setting the interval to a negative value or 0 will cancel sending of periodic Pong messages.
    
    Parameters:
    heartbeatInterval - interval between periodic Pong messages in milliseconds.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getRemoteAddr
```
public String getRemoteAddr()
```
    Get the Internet Protocol (IP) address of the client or last proxy that sent the request.
    
    Returns:
    a String containing the IP address of the client that sent the request or null when method is called on client-side.

Class TyrusSession

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getProtocolVersion

getNegotiatedSubprotocol

getAsyncRemote

getBasicRemote

isOpen

close

close

getMaxBinaryMessageBufferSize

setMaxBinaryMessageBufferSize

getMaxTextMessageBufferSize

setMaxTextMessageBufferSize

getOpenSessions

getRemoteSessions

getAllSessions

getNegotiatedExtensions

getMaxIdleTimeout

setMaxIdleTimeout

isSecure

getContainer

addMessageHandler

addMessageHandler

addMessageHandler

getMessageHandlers

removeMessageHandler

getRequestURI

getRequestParameterMap

getPathParameters

getUserProperties

getDistributedProperties

getQueryString

getId

getUserPrincipal

broadcast

broadcast

getHeartbeatInterval

setHeartbeatInterval

toString

getRemoteAddr