com.lightstreamer.jmx

Interface SessionMBean

public interface SessionMBean

Multiple SessionMBean instances exist in the system, where each one is related to one Session currently active. Every active Session can be bound to 0 or 1 SessionMBean instances. Each SessionMBean instance is created by Lightstreamer Server right after the creation of a Session and destroyed just before that Session terminates.

The main services provided by each MBean instance are:

• Various static properties of the session (like getAdapterSet() and getStartTime()).
• Various characteristics of the related client (like getRemoteIP(), getClientType(), and getUsername()).
• The current state of the session (like getIsPrestarted()), together with a destroySession() operation.
• Information on how the session is working (like getIsOnWS() and getIsStreaming()).
• Statistics about update events sent to the clients, i.e. "item updates", cumulated on all subscriptions (like getCumulItemUpdates()).
  These statistics are similar to the ones offered by the StreamMBean, but only for this session.
• Statistics about network throughput (here also named "bandwidth") due to the update events sent to the clients (like getMaxBandwidthKbps()).
  These statistics are similar to the ones offered by the StreamMBean, but only for this session.
• Statistics about update events due to be sent to the clients but not sent, as conflated (i.e. "filtered") or lost for overflow (like getNewFilteredEvents()).
  These statistics are similar to the ones offered by the StreamMBean, but only for this session.
• The same statistics about update events, but for single subscribed items (like getCumulRealTimeEvents(java.lang.String, java.lang.String)).
• Statistics about messages sent by the clients through "sendMessage", and the related network throughput (like getCumulMessageBytes()).
  These statistics are similar to the ones offered by the StreamMBean, but only for this session.
• Dynamic handling of bandwidth limits posed on the session (like setAllocatedMaxBandwidthKbps(java.lang.Double) and getAllocatedMaxBandwidthKbps()).
• Information on the subscriptions currently in place (like getSubscriptionList(java.lang.String) and getTotalFields()).
• Some information on the client activity in terms of control requests (like getCumulPollingRequests() and getCumulControlRequests()).

SessionMBean name pattern:
"com.lightstreamer:type=Session,sessionId=<sessionId>"

However, the creation of SessionMBeans can be disabled and it is disabled by default configuration (see <disable_session_mbeans>). In that case, only a fake MBean of this type with no associated Session is created, as a reminder that the creation can be enabled.
Alternatively, through the same static configuration, it is possible to disable only the computation of statistics based on periodic sampling (see getSampledStatisticsEnabled).

Method Summary

Modifier and Type	Method and Description
java.lang.Boolean	destroySession() Disconnect the Client and destroys this Session.
java.lang.String	getAdapterSet()
java.lang.Double	getAllocatedBandwidthKbps()
java.lang.Double	getAllocatedMaxBandwidthKbps()
java.lang.String	getClientType()
java.lang.String	getClientVersion()
java.lang.Long	getCumulControlRequests()
java.lang.Long	getCumulControlRequestsFailed()
java.lang.Long	getCumulFilteredEvents()
java.util.List<java.lang.Long>	getCumulFilteredEvents(java.lang.String itemName, java.lang.String dataAdapter)
java.lang.Long	getCumulItemUpdates()
java.lang.Long	getCumulLostEvents()
java.util.List<java.lang.Long>	getCumulLostEvents(java.lang.String itemName, java.lang.String dataAdapter)
java.lang.Long	getCumulMessageBytes()
java.lang.Long	getCumulMessages()
java.lang.Long	getCumulOutboundBytes()
java.lang.Long	getCumulPollingRequests()
java.util.List<java.lang.Long>	getCumulRealTimeEvents(java.lang.String itemName, java.lang.String dataAdapter)
java.lang.Long	getCumulSendMessageRequests()
java.lang.Long	getCumulStreamingRequests()
java.lang.Long	getCumulSubscriptionRequests()
java.lang.Long	getCumulUnsubscriptionRequests()
java.lang.Double	getCurrentBandwidthKbps()
java.lang.Double	getCurrentMessageThroughputKbps()
java.lang.Boolean	getIsClosed()
java.lang.Boolean	getIsOnHTTP()
java.lang.Boolean	getIsOnWS()
java.lang.Boolean	getIsPolling()
java.lang.Boolean	getIsPrestarted()
java.lang.Boolean	getIsStreaming()
java.lang.Double	getItemUpdateFrequency()
java.lang.Integer	getLocalPort()
java.lang.Double	getMaxBandwidthKbps()
java.lang.Integer	getMaxFilteredEvents()
java.lang.Double	getMaxItemUpdateFrequency()
java.lang.Integer	getMaxLostEvents()
java.lang.Double	getMaxMessageFrequency()
java.lang.Double	getMaxMessageThroughputKbps()
java.lang.Double	getMessageFrequency()
java.lang.Integer	getNewFilteredEvents()
java.lang.Integer	getNewLostEvents()
java.lang.String	getRemoteHostname()
java.lang.String	getRemoteIP()
java.lang.Integer	getRemotePort()
java.lang.Boolean	getSampledStatisticsEnabled()
java.lang.String	getSessionId()
java.util.Date	getStartTime()
java.util.List<java.lang.String>	getSubscriptionList(java.lang.String dataAdapter)
java.lang.Integer	getTotalFields()
java.lang.Long	getTotalSubscriptions()
java.lang.String	getUserAgent()
java.lang.String	getUsername()
void	setAllocatedMaxBandwidthKbps(java.lang.Double bandwidth)

Method Detail

getSessionId

java.lang.String getSessionId()

Returns:

The sessionId of this Session.

getStartTime

java.util.Date getStartTime()

Returns:

The timestamp of the creation of this Session.

getLocalPort

java.lang.Integer getLocalPort()

Returns:

The local TCP port of the server socket of the current (or last) Streaming or Polling Connection of this Session.

getRemoteIP

java.lang.String getRemoteIP()

Returns:

The remote IP address of the current (or last) Client connected to this Session.

getRemoteHostname

java.lang.String getRemoteHostname()

Returns:

The remote hostname of the current (or last) Client connected to this Session. Note that the determination of the host name may cause some delay.

getRemotePort

java.lang.Integer getRemotePort()

Returns:

The remote TCP port of the client socket of the current (or last) Streaming or Polling Connection.

getUserAgent

java.lang.String getUserAgent()

Returns:

The user agent of the Client bound to this Session. This value is obtained from the "User-Agent" field of the HTTP header of the current (or last) Streaming or Polling Request. A length limit is applied, so as not to store values too long.

getClientType

java.lang.String getClientType()

Returns:

The type of client API that was used to open this session. This value is not available for some old clients, in such cases it will be null.

getClientVersion

java.lang.String getClientVersion()

Returns:

The signature, including version and build number, of the client API that was used to open this session. This value is not available for some old clients and it may not be available for custom clients; in such cases it will be null. For other old clients, the signature may be only partially complete.

getUsername

java.lang.String getUsername()

Returns:

The username of the User owning this Session. It may be null.

getAdapterSet

java.lang.String getAdapterSet()

Returns:

The name of the Adapter Set bound to this Session.

getSubscriptionList

java.util.List<java.lang.String> getSubscriptionList(java.lang.String dataAdapter)

Parameters:

dataAdapter - the name of a Data Adapter belonging to the Adapter Set related with the Session, or null; if null, all Data Adapters within the Adapter Set are searched and all subscriptions found are aggregated.

Returns:

The list of Items currently subscribed to by the Client on this Session. Expressed as an ArrayList of Strings, where each String contains the itemName of the Item. The list is ordered from the earliest to the latest subscription requests; hence, Items used in multiple subscriptions are reported multiple times.

getTotalSubscriptions

java.lang.Long getTotalSubscriptions()

Returns:

The total number of Items currently subscribed to by the Client on this Session. Items used in multiple subscription requests are reported multiple times.

getTotalFields

java.lang.Integer getTotalFields()

Returns:

The total number of Fields currently subscribed to by the Client on this Session. The fields are aggregated over all the current subscriptions. Any field used in multiple subscriptions, even for the same Item, is counted multiple times.

getSampledStatisticsEnabled

java.lang.Boolean getSampledStatisticsEnabled()

Returns:

true if the collection of statistics based on periodic sampling is enabled. If disabled, some of the properties of this MBean will be null (see the various descriptions for details). This enablement can only be managed through static configuration (see <disable_session_mbeans>).

getCumulOutboundBytes

java.lang.Long getCumulOutboundBytes()

Returns:

The total (cumulative) number of bytes sent for this Session. The value aggregates all HTTP contents sent on all the Connections that have been bound to the Session.

getCumulItemUpdates

java.lang.Long getCumulItemUpdates()

Returns:

The total (cumulative) number of Item Updates sent for this Session.

getItemUpdateFrequency

java.lang.Double getItemUpdateFrequency()

Returns:

The frequency of outbound Item Updates sent for this Session in the last sampling period. It is expressed as updates per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getMaxItemUpdateFrequency

java.lang.Double getMaxItemUpdateFrequency()

Returns:

The maximum frequency of outbound Item Updates reached for this Session. It is expressed as updates per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getIsStreaming

java.lang.Boolean getIsStreaming()

Returns:

true if a Streaming connection is currently attached to this Session.

getIsPolling

java.lang.Boolean getIsPolling()

Returns:

true if a Polling Connection is currently attached to this Session or the Session is being kept alive, waiting for a Polling Connection.

getIsPrestarted

java.lang.Boolean getIsPrestarted()

Returns:

true if the session is currently in "prestarted" state. By prestarted Session we mean a session for which no related requests have been received yet. Binding a session with a new connection also brings it out of the prestarted state. Prestarted session are not included in various session count statistics.

getIsOnHTTP

java.lang.Boolean getIsOnHTTP()

Returns:

true if a HTTP Streaming or HTTP Polling connection is currently attached to this Session (or the Session is being kept alive, after a HTTP connection, waiting for a new Connection). Note that a Session can switch between HTTP and WebSocket during its life.

getIsOnWS

java.lang.Boolean getIsOnWS()

Returns:

true if a WS Streaming or WS Polling connection is currently attached to this Session (or the Session is being kept alive, after a WS connection, waiting for a new Connection). Note that a Session can switch between HTTP and WebSocket during its life.

getCumulStreamingRequests

java.lang.Long getCumulStreamingRequests()

Returns:

The total (cumulative) number of Streaming Requests received for this Session.

getCumulPollingRequests

java.lang.Long getCumulPollingRequests()

Returns:

The total (cumulative) number of Polling Requests received for this Session. Note that Streaming Sessions may, in their initial phase receive Polling Requests; in that case, they will be included in this count.

getCumulControlRequests

java.lang.Long getCumulControlRequests()

Returns:

The total (cumulative) number of Control Requests received for this Session. The count includes Requests for subscriptions, unsubscriptions, message submission and change of constraints. Note that single HTTP Requests issued to the Server may specify multiple Control Requests. The count does not include incorrect or late Requests that could not be submitted to the Session.

getCumulSubscriptionRequests

java.lang.Long getCumulSubscriptionRequests()

Returns:

The total (cumulative) number of Requests for table subscriptions received for this Session (according with the notes for getCumulControlRequests()). The count may include duplicated requests, that will be ignored.

getCumulUnsubscriptionRequests

java.lang.Long getCumulUnsubscriptionRequests()

Returns:

The total (cumulative) number of Requests for table unsubscriptions received for this Session (according with the notes for getCumulControlRequests()). The count may include duplicated requests, that will be ignored.

getCumulSendMessageRequests

java.lang.Long getCumulSendMessageRequests()

Returns:

The total (cumulative) number of Requests for message submission received for this Session (according with the notes for getCumulControlRequests()). The count may include duplicated or delayed requests, that will be ignored.

getCumulControlRequestsFailed

java.lang.Long getCumulControlRequestsFailed()

Returns:

The total (cumulative) number of Control Requests received for this Session (according with the notes for getCumulControlRequests()) whose processing has failed. This is usually due to authorization restrictions posed by the Metadata Adapter. The count may include asynchronous message submission requests that have eventually failed.

getCurrentBandwidthKbps

java.lang.Double getCurrentBandwidthKbps()

Returns:

The current outbound bandwidth used by the Server for this Session (in the last sampling period). The count includes network overheads. It is expressed as Kilobits per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getMaxBandwidthKbps

java.lang.Double getMaxBandwidthKbps()

Returns:

The maximum outbound bandwidth used by the Server for this Session. The count includes network overheads. It is expressed as Kilobits per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getAllocatedBandwidthKbps

java.lang.Double getAllocatedBandwidthKbps()

Returns:

The limit on the outbound bandwidth currently enforced for this Session. The count includes network overheads. It is expressed as Kilobits per second; the value has a three decimal precision; a 0 value means that no limit is set.

Edition Note:

Bandwidth control is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please check out the com.lightstreamer.Edition bean.

getAllocatedMaxBandwidthKbps

java.lang.Double getAllocatedMaxBandwidthKbps()

Returns:

The maximum outbound bandwidth allowed by the Server for this Session. The limit includes network overheads. Note that the client can ask for a smaller bandwidth limit; the currently enforced limit is reported by getAllocatedBandwidthKbps(). It is expressed as Kilobits per second; the value has a three decimal precision; a 0 value means that no limit is set; a -1 value means that no limit can be set because of custom license restrictions.

Edition Note:

Bandwidth control is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please check out the com.lightstreamer.Edition bean.

setAllocatedMaxBandwidthKbps

void setAllocatedMaxBandwidthKbps(java.lang.Double bandwidth)

Parameters:

bandwidth - The maximum outbound bandwidth to be allowed by the Server for this Session. The limit includes network overheads. Note that the client can ask for a smaller bandwidth limit; the currently enforced limit is reported by getAllocatedBandwidthKbps(). It is expressed as Kilobits per second; a 0 value means that no limit is set.

Edition Note:

Bandwidth control is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please check out the com.lightstreamer.Edition bean.

getCumulMessageBytes

java.lang.Long getCumulMessageBytes()

Returns:

The total (cumulative) number of bytes submitted to the Metadata Adapter, for this Session, in the life of the Server and related to Client Messages associated to sendMessage requests. The count includes the byte length of the String objects carrying the messages, according with their internal UTF-16 encoding.

getCumulMessages

java.lang.Long getCumulMessages()

Returns:

The total (cumulative) number of Client Messages submitted to the Metadata Adapter, for this Session, in the life of the Server.

getMessageFrequency

java.lang.Double getMessageFrequency()

Returns:

The frequency of Client Messages submitted to the Metadata Adapter, for this Session, in the last sampling period. It is expressed as messages per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getMaxMessageFrequency

java.lang.Double getMaxMessageFrequency()

Returns:

The maximum frequency of Client Messages submitted to the Metadata Adapter, for this Session, reached in the life of the Server. It is expressed as messages per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getCurrentMessageThroughputKbps

java.lang.Double getCurrentMessageThroughputKbps()

Returns:

The current throughput (measured in the last sampling period) related to the submission to the Metadata Adapter, for this Session, of Client Messages associated to sendMessage requests. The count includes the byte length of the String objects carrying the messages, according with their internal UTF-16 encoding. It is expressed as Kilobits per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getMaxMessageThroughputKbps

java.lang.Double getMaxMessageThroughputKbps()

Returns:

The maximum throughput (occurred in the life of the Server) related to the submission to the Metadata Adapter, for this Session, of Client Messages associated to sendMessage requests. The count includes the byte length of the String objects carrying the messages, according with their internal UTF-16 encoding. It is expressed as Kilobits per second; the value has a three decimal precision. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getNewLostEvents

java.lang.Integer getNewLostEvents()

Returns:

The number of lost events in the last sampling period. Events can only be lost because of buffer size restrictions posed for safety purpose. This applies to Items subscribed to in RAW mode, or in any mode with unfiltered dispatching specified. This also applies to items subscribed to in COMMAND mode with filtered dispatching, restricted to "ADD" and "DELETE" events only (note that those events can also be filtered through matching). Any lost event is also notified to the client. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getMaxLostEvents

java.lang.Integer getMaxLostEvents()

Returns:

The max number of lost events (as specified for getNewLostEvents()) in a sampling period. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getCumulLostEvents

java.lang.Long getCumulLostEvents()

Returns:

The total (cumulative) number of lost events (as specified for getNewLostEvents()).

getNewFilteredEvents

java.lang.Integer getNewFilteredEvents()

Returns:

The number of filtered events in the last sampling period. Events can be filtered only if this is allowed by the item subscription mode; in that case, no information on the current state of the item is lost and the client is not notified. Events lost as specified for getNewLostEvents() are not considered as filtered. Events discarded because of the application of a "selector" are also included in this count, regardless of the subscription mode. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getMaxFilteredEvents

java.lang.Integer getMaxFilteredEvents()

Returns:

The max number of filtered events (as specified for getNewFilteredEvents()) in a sampling period. However, the returned value is always null if the collection of periodic statistics is disabled (see getSampledStatisticsEnabled()).

getCumulFilteredEvents

java.lang.Long getCumulFilteredEvents()

Returns:

The total (cumulative) number of filtered events (as specified for getNewFilteredEvents()).

getCumulRealTimeEvents

java.util.List<java.lang.Long> getCumulRealTimeEvents(java.lang.String itemName,
                                                      java.lang.String dataAdapter)

Parameters:

itemName - an Item name.

dataAdapter - the name of a Data Adapter belonging to the Adapter Set related with the Session, or null; if null, all Data Adapters within the Adapter Set are searched and all subscriptions found are aggregated.

Returns:

The total (cumulative) number of real-time events (hence, not including snapshot events) disaggregated for each of the current subscriptions of the specified Item requested by the Client. Expressed as a List of Long. The list is ordered from the earliest to the latest subscription request for the Item (as in getSubscriptionList(java.lang.String)).

getCumulLostEvents

java.util.List<java.lang.Long> getCumulLostEvents(java.lang.String itemName,
                                                  java.lang.String dataAdapter)

Parameters:

itemName - an Item name.

dataAdapter - the name of a Data Adapter belonging to the Adapter Set related with the Session, or null; if null, all Data Adapters within the Adapter Set are searched and all subscriptions found are aggregated.

Returns:

The total (cumulative) number of lost events (as specified for getNewLostEvents()) disaggregated for each of the current subscriptions of the specified Item requested by the Client. Expressed as a List of Long. The list is ordered from the earliest to the latest subscription request for the Item (as in getSubscriptionList(java.lang.String)).

getCumulFilteredEvents

java.util.List<java.lang.Long> getCumulFilteredEvents(java.lang.String itemName,
                                                      java.lang.String dataAdapter)

Parameters:

itemName - an Item name.

dataAdapter - the name of a Data Adapter belonging to the Adapter Set related with the Session, or null; if null, all Data Adapters within the Adapter Set are searched and all subscriptions found are aggregated.

Returns:

The total (cumulative) number of filtered events (as specified for getNewFilteredEvents()) disaggregated for each of the current subscriptions of the specified Item requested by the Client. Expressed as a List of Long. The list is ordered from the earliest to the latest subscription request for the Item (as in getSubscriptionList(java.lang.String)).

destroySession

java.lang.Boolean destroySession()

Disconnect the Client and destroys this Session.

Returns:

True if operation succeeded. False if operation failed.

getIsClosed

java.lang.Boolean getIsClosed()

Returns:

true if the Session has just been closed; this may happen in transient cases, when the MBean is about to be removed. In particular, this is the case until the termination of the invocation of the Session's notifySessionClose; in this condition, all the cumulative statistics provided are still valid.