Event types used within SessionPropertiesListener.onSessionEvent
Register a listener that will be notified of client session events.
These events may occur when a client session is opened, becomes disconnected, reconnects, fails over, or is closed. Events may also occur if any of the session properties of the client session change as a result of a call to ClientControl.setSessionProperties.
When a listener is first added, by default, it will be called with STATE events for all currently open sessions. The amount of data transferred from the server is proportional to the number of connected clients and is potentially large, especially if session properties are requested. To mitigate this the caller can choose to only receive events for sessions started after a specified time (e.g. from now), in which case events will only be received for sessions that start after that time.
A control session can register any number of listeners with different parameters, but the cost in network traffic should be carefully considered.
When a listener is no longer required, it may be closed using the Registration provided by the Promise result.
The parameters parameter is used to define the level of event
detail required.
the listener to be called with session event notifications
a SessionEventParameters object defining the level of event detail required.
a Promise that completes when the listener has been registered, returning a Registration which can be used to unregister the listener.
Otherwise, an error will be returned. Common reasons for failure include:
parameters was invalid;
Changes the assigned roles of one or more sessions.
Initially a session has a set of roles assigned during authentication.
The set of assigned roles can be obtained from the session's $Roles
session property.
When a session's assigned roles change, its $Roles property changes
accordingly. Changing the assigned roles can change the READ_TOPIC
permissions granted to the session. The session's subscriptions will be
updated accordingly.
The same role must not occur in both rolesToRemove and
rolesToAdd sets. Either set can be an empty set but not both.
Either a SessionId that identifies a single
client session, or a filter that identifies the set
of client sessions for which the change will be
applied. If a string is passed and is a parsable
SessionId, it is treated as a SessionId, otherwise
it assumed to be a filter.
a set of roles to be removed from the session. If one or more roles from the list are not currently assigned, they are ignored.
a set of roles to be added to the session. If one or more roles from the list are already assigned, they are ignored.
a Promise that resolves when session roles have been changed.
If successful, the result resolves with an integer value which represents a number of sessions that have matched the filter and for which the specified role changes have been applied.
Otherwise, the Promise fails with an Error. Common reasons for failure include:
MODIFY_SESSION permission;
SessionId was supplied and there is no session with
the given sessionId;
rolesToRemove and rolesToAdd
are empty sets.
null or undefined
Close one or more client sessions.
Example:
session.clients.close(otherSessionID).then(function() {
// Other session has been closed
}, function(err) {
// There was an error when trying to close the other session
});Either a SessionId that identifies a single
client session, or a filter that identifies the set
of client sessions for which the change will be
applied. If a string is passed and is a parsable
SessionId, it is treated as a SessionId, otherwise
it assumed to be a filter.
a Promise that resolves to the number of affected sessions
If unsuccessful, the promise will be rejected. Common reasons for failure include:
null or undefined
Returns details of the session (if any) that holds a named session lock.
the lock name
a Promise that resolves with details of the named lock.
If the Promise resolves normally then it returns the details of the session that currently holds the lock, or null if no session holds the named lock.
Otherwise, the Promise will reject with a {@link CompletionException}. Common reasons for failure, listed by the exception reported as the {@link CompletionException#getCause() cause}, include:
Returns details of all session locks currently held.
a Promise that resolves with details of all session locks that are currently held.
If the Promise resolves normally then it returns a map of session locks keyed on the lock name where the value identifies the session currently holding the lock. If there are no session locks currently held by anybody this will return an empty map.
Otherwise, the Promise will reject with a {@link CompletionException}. Common reasons for failure, listed by the exception reported as the {@link CompletionException#getCause() cause}, include:
Query the server for property values of a specified client session.
See PropertyKeys for a list of the available fixed property keys.
To request all fixed properties ALL_FIXED_PROPERTIES may be included as the key.
To request all user properties ALL_USER_PROPERTIES may be included as the key.
Example:
// Get values of all fixed properties for client whose session id is 'id'.
session.clients.getSessionProperties(id, PropertyKeys.ALL_FIXED_PROPERTIES);Example:
// Get values of the 'FOO' and 'BAR' properties for client whose session id is 'id'.
session.clients.getSessionProperties(id, ['FOO', 'BAR']).then(function(properties) {
console.log('Received properties for session', properties);
}, function(err) {
console.log('Unable to receive properties: ', err);
});specifies the keys of the property values required.
a Promise for this operation
If unsuccessful, the promise will be rejected. Common reasons for failure include:
Returns a map of the current topic selection state for a specified session, keyed on topic selection scope.
Each scope will have an ordered list of selections and/or deselections.
The server conflates selections, so if there has been a selection that is later rendered redundant by a deselection it will not be present. A scope that has been used but fully deselected will therefore not be present in the map and therefore no entry will have an empty list.
If the session has no current selections the map will be empty.
a Promise that completes when a response is received from the server with the results of the operation.
If the task completes successfully, the Promise result will be a map of an ordered list of TopicSelections keyed on scope. If the default scope is in use the key will be Topics.DEFAULT_SELECTION_SCOPE. If unsuccessful, the promise will be rejected. Common reasons for failure include:
null or undefined
Control client queue conflation.
Each session begins with conflation enabled or disabled based on the queue configuration of the connector it is using. This method allows conflation to be enabled or disabled for specific sessions at runtime.
Conflation is the process of merging or discarding topic updates queued for a session to reduce the server memory footprint and network data. Conflation needs to be enabled for a session and a policy configured for the topic to have an effect. Policies are configured on a per-topic basis using the topic property CONFLATION.
Either a SessionId that identifies a single
client session, or a filter that identifies the set
of client sessions for which the change will be
applied. If a string is passed and is a parsable
SessionId, it is treated as a SessionId, otherwise
it assumed to be a filter.
a Promise that resolves to the number of affected sessions
If the conflation policy was updated for the identified session, the Promise will resolve successfully.
Otherwise, the Promise fails with an Error. Common reasons for failure include:
MODIFY_SESSION permission;
null or undefined
Send a request to the server to change the user-defined session properties for a session.
It is also permissible to change the values of the following fixed session properties :-
$Country - will be normalised to upper case $Language - will be normalised to lower case $Latitude - Invalid value will be set to "NaN" $Longitude - Invalid value will be set to "NaN"
If values are provided for any other fixed session properties they will be ignored.
Example:
// Add a new session property for client whose session id is 'id'.
session.clients.setSessionProperties(id, { 'foo': 'bar' });
// Remove a session property for client whose session id is 'id'.
session.clients.setSessionProperties(id, { 'foo': null }).then(function(properties) {
console.log('Properties changed ', properties);
}, function(err) {
console.log('Unable to change properties: ', err);
});identifies the client session
the properties to change. Each entry in the map is a
property name and the new value. If the value is
null , any existing property with that
name will be removed (unless it is a fixed property).
Otherwise if the property name does not match any existing
property, that entry will be added as a new property
(although properties starting $ will be ignored).
a Promise for this operation. If the session properties
were updated, the result type is a map of properties that
changed with their previous values. If no properties were
changed, the map will be empty. If any new properties were
added, the values in the map will be null to indicate that
they do not have an old value.
Otherwise, an error will be returned. Common reasons for failure include:
null or undefined
Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties.
It is also permissible to change the values of the following fixed session properties :-
$Country - will be normalised to upper case $Language - will be normalised to lower case $Latitude - Invalid value will be set to "NaN" $Longitude - Invalid value will be set to "NaN"
If values are provided for any other fixed session properties they will be ignored.
Example:
// Remove session property {job=employee}
session.clients.setSessionPropertiesByFilter("job is 'employee'", { 'job': null }).then(function () {
// All sessions satisfied the filter have updated their properties
}, function (err) {
console.log("Failed to update properties ", err);
});session filter
the properties to change. Each entry in the map is a
property name and the new value. If the value is
null , any existing property with that
name will be removed (unless it is a fixed property).
Otherwise if the property name does not match any existing
property, that entry will be added as a new property
(although properties starting $ will be ignored).
a Promise that resolves when session properties have been changed.
If successful, the result resolves with an integer value which represents a number of sessions that have matched the filter and for which the specified properties changes have been applied.
The operation can fail, common reasons for failure include:
null or undefined
Register a listener that will be notified when client sessions are opened, disconnected, reconnected, closed or when selected session property values are updated.
This only notifies sessions connecting to the same server as the current session and therefore if the Diffusion system is operating as a cluster then the only way to receive notifications for sessions at all cluster members would be to connect separate sessions (and listeners) to each cluster member. When connecting to a cluster it is recommended that the addSessionEventListener method is used instead.
When a listener is first set, it will be called with the required properties of all currently open client sessions. The amount of data transferred from the server is proportional to the number of connected clients and is potentially large. The amount of data can be reduced using the requiredProperties parameter.
The requested property set controls the level of detail provided and whether the listener is called for updates to sessions. If no properties are requested then the listener is not called when session properties are updated.
To request all fixed properties ALL_FIXED_PROPERTIES should be included as a key and any other fixed property keys would be ignored. To request all user properties ALL_USER_PROPERTIES should be included as a key and any other user property keys supplied would be ignored.
Example:
// Specify desired properties to listen to
var props = diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES;
// Create the listener
var listener = {
onActive : function(deregister) {
// Listener is active
},
onSessionOpen : function(sessionID, properties) {
// A session has been opened
},
onSessionEvent : function(sessionID, event, properties, previous) {
// A session's properties have changed (specified by 'event')
},
onSessionClose : function(sessionID, properties, reason) {
// A session has closed
},
onClose : function() {
// Listener is closed
}
}
session.clients.setSessionPropertiesListener(props, listener).then(function() {
// Registration was succesful
}, function(err) {
// There was an error registering the session listener
});a set of required property keys.
the listener to register
a Promise for this operation.
Subscribe one or more client sessions to topics.
To subscribe a single known session (anywhere in a cluster), a session id may be provided; alternatively, a Session Filter may be used, in which case all sessions (anywhere in a cluster) that satisfy the filter will be subscribed.
New subscriptions will be established for existing topics that match the provided topic selector and for which the subscribed session has {@code READ_TOPIC} permission. The topic selector will be added to the topic selections of the subscribed session, and re-evaluated when new topics are added or the session's security roles change.
A session that does not have {@code SELECT_TOPIC} permission for a topic cannot subscribe directly, but can be subscribed indirectly using this method.
The second argument of this function can be a string, a TopicSelector, or a non-empty of strings and TopicSelectors.
Example:
// Subscribe a single session via SessionID
session.clients.subscribe(otherSessionID, ">foo").then(function() {
// Subscribed 'otherSession' to topic "foo"
}, function(err) {
// Subscription failed
console.log("Failed to subscribe session", err);
});Example:
// Subscribe multiple sessions via a Session Filter
session.clients.subscribe("$ClientType IS 'JAVA'", ">foo").then(function(selected) {
console.log("Subscribed " + selected + " sessions to topic 'foo'");
}, function(err) {
// Subscription failed
console.log("Failed to subscribe sessions", err);
});Either a SessionId that identifies a single
client session, or a filter that identifies the set
of client sessions for which the change will be
applied. If a string is passed and is a parsable
SessionId, it is treated as a SessionId, otherwise
it assumed to be a filter.
the Topic Selector(s) to subscribe to
(optional) specifies the scope of the selection. See Topic Selection Scopes. Defaults to DEFAULT_SELECTION_SCOPE.
a Promise for this operation. If subscribing with a session filter, the success callback will be given the number of sessions selected by the filter.
If unsuccessful, the promise will be rejected. Common reasons for failure include:
null or undefined
Unsubscribe one or more client sessions from topics.
To unsubscribe a single known session (anywhere in a cluster), a session id may be provided; alternatively, a Session Filter may be used, in which case all sessions (anywhere in a cluster) that satisfy the filter will be unsubscribed.
The second argument of this function can be a string, a TopicSelector, or a non-empty of strings and TopicSelectors.
Example:
// Unsubscribe a single session via SessionID
session.clients.unsubscribe(otherSessionID, ">foo").then(function() {
// Unsubscribed 'otherSession' from topic "foo"
}, function(err) {
// Unsubscription failed
console.log("Failed to unsubscribe session", err);
});Example:
// Unsubscribe multiple sessions via a Session Filter
session.clients.unsubscribe("$ClientType IS 'JAVA'", ">foo").then(function(selected) {
console.log("Unsubscribed " + selected + " sessions from topic 'foo'");
}, function(err) {
// Unsubscription failed
console.log("Failed to unsubscribe sessions", err);
});Either a SessionId that identifies a single
client session, or a filter that identifies the set
of client sessions for which the change will be
applied. If a string is passed and is a parsable
SessionId, it is treated as a SessionId, otherwise
it assumed to be a filter.
the Topic Selector to unsubscribe from
(optional) specifies the scope of the selection. See Topic Selection Scopes. Defaults to DEFAULT_SELECTION_SCOPE.
a Promise for this operation. If unsubscribing with a session filter, the success callback will be given the number of sessions selected by the filter
If unsuccessful, the promise will be rejected. Common reasons for failure include:
null or undefined
Unsubscribe topics from all topic selection scopes.
This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests and will apply to all scopes in use.
Either a SessionId that identifies a single
client session, or a filter that identifies the set
of client sessions for which the change will be
applied. If a string is passed and is a parsable
SessionId, it is treated as a SessionId, otherwise
it assumed to be a filter.
the Topic Selector to unsubscribe from
a Promise for this operation. If unsubscribing with a session filter, the success callback will be given the number of sessions selected by the filter
If unsuccessful, the promise will be rejected. Common reasons for failure include:
null or undefined
This feature provides the ability for a client session to control other client sessions.
It allows for notifications of client session events as well as the ability to manage client sessions (forcibly closing them etc).
It also provides the ability to monitor session locks.
This feature also provides the ability to query the topic selections of another session.
Access control
A session must have VIEW_SESSION permission to be able to listen for notifications using ClientControl.addSessionEventListener or ClientControl.setSessionPropertiesListener, or get properties of sessions.
In addition, REGISTER_HANDLER permission is required to add a session event listener, a session property listener, or queue event handler.
In order to perform operations that change a specific session's state (such as conflating, closing sessions, or changing roles), MODIFY_SESSION permission is required.
To directly subscribe other sessions to topics, a session must have MODIFY_SESSION permission, and SELECT_TOPIC permission for the the topic selector used for subscription. The subscribed sessions will only be subscribed to matching topics for which they have READ_TOPIC permission.
To directly unsubscribe other sessions, a session must have MODIFY_SESSION permission, and SELECT_TOPIC permission for the topic selector used for unsubscription.
Getting the topic selections for a specified session requires VIEW_SESSION permission.
Accessing the feature
This feature may be obtained from a session as follows:
var clients = session.clients;