Namespace: clients

Session. clients

Client control feature.


Provides the ability for a client session to control other client sessions.

Properties:
Name Type Description
SessionEventType Session.clients.SessionEventType

Event types used within Session.clients.SessionPropertiesListener#onSessionEvent.

Example

var clients = session.clients;

Classes

SessionPropertiesListener

Members

<static, readonly> SessionEventType

Properties:
Name Type Default Description
UPDATED 0

One or more relevant session properties have been updated.

RECONNECTED 1

A session has reconnected.

FAILED_OVER 2

A session has failed over from one server to another in a cluster.

DISCONNECTED 3

A session has disconnected.

Example
session.clients.setSessionPropertiesListener(props, {
    // ...

    onSessionEvent : function(sessionID, event, properties, previous) {
         switch (event) {
             case session.clients.SessionEventType.DISCONNECTED :
                 console.log(sessionID + " has disconnected");
                 break;
             case session.clients.SessionEventType.RECONNECTED :
                 console.log(sessionID + " has reconnected");
                 break;
         }
    }

    // ...
});

Methods

close(sessionId) → {Result.<Void>}

Close a client session.

Parameters:
Name Type Description
sessionId String | SessionId

identifies the client session to close

Returns:
  • A Result for this operation.
Type
Result.<Void>
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
});

getSessionProperties(sessionID, requiredProperties) → {Result}

Query the server for property values of a specified client session.


See Session.clients.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.

Parameters:
Name Type Argument Description
sessionID String

Identifies the client session.

requiredProperties Array <optional>

Specifies the keys of the property values required.

Returns:

A Result for this operation.

Type
Result
Examples
// Get values of all fixed properties for client whose session id is 'id'.
session.clients.getSessionProperties(id, diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES);
// 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);
});

setSessionProperties(sessionID, properties) → {Result.<Map>}

Send a request to the server to change the user-defined session properties for a session.

Parameters:
Name Type Description
sessionID String

identifies the client session

properties Map.<String, String>

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. Otherwise if the property name does not match any existing property, that entry will be added as a new property.

Returns:

A Result 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 wil be returned. Common reasons for failure include:

  • diffusion.errors.ACCESS_DENIED if the calling session does not have sufficient permission.
  •     <li>
        diffusion.errors.NO\_SUCH\_SESSION if the calling session
        is closed before the response was delivered.</li>
    
        <li>
        diffusion.errors.SESSION\_CLOSED if the calling session is closed.</li>
        </ul>
Type
Result.<Map>
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);
});

setSessionPropertiesByFilter(filter, properties) → {Result.<Void>}

Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties.

Parameters:
Name Type Description
filter String

session filter

properties Map.<String, String>

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. Otherwise if the property name does not match any existing property, that entry will be added as a new property.

Returns:

A Result for this operation. The operation can fail, common reasons for failure include:

  • diffusion.errors.ACCESS_DENIED if the calling session does not have sufficient permission.
  •     <li>
        diffusion.errors.NO\_SUCH\_SESSION if the calling session is closed
        before the response was delivered.</li>
    
        <li>
        diffusion.errors.SESSION\_CLOSED if the calling session is closed.</li>
        </ul>
Type
Result.<Void>
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);
});

setSessionPropertiesListener(requiredProperties, listener) → {Result.<undefined>}

Register a listener that will be notified when client sessions are opened, disconnected, reconnected, closed or when selected session property values are updated.

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.

Parameters:
Name Type Description
requiredProperties Array

A set of required property keys.

listener Session.clients.SessionPropertiesListener

The listener to register

Returns:

A Result.<undefined> for this operation.

Type
Result.<undefined>
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
});

subscribe(session, selector) → {Result.<Number>}

Subscribe one or more client sessions to topics.

To subscribe a single known session, a session id may be provided; alternatively, a Session Filter may be used, in which case all sessions that satisfy the filter will be subscribed.

Parameters:
Name Type Description
session String

The Session ID or Session Filter

selector String

The Topic Selector to subscribe to

Returns:
  • A Result.<Number> for this operation. If subscribing with a session filter, the success callback will be given the number of sessions selected by the filter
Type
Result.<Number>
Examples
// 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);
});
// Subscribe multiple sesssions 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);
});

unsubscribe(session, selector) → {Result.<Number>}

Unsubscribe one or more client sessions from topics.

To unsubscribe a single known session, a session id may be provided; alternatively, a Session Filter may be used, in which case all sessions that satisfy the filter will be unsubscribed.

Parameters:
Name Type Description
session String

The Session ID or Session Filter

selector String

The Topic Selector to unsubscribe from

Returns:
  • A Result.<Number> for this operation. If unsubscribing with a session filter, the success callback will be given the number of sessions selected by the filter
Type
Result.<Number>
Examples
// 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);
});
// Unsubscribe multiple sesssions 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);
});