Interface ClientControl

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.

since

6.3

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
});

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);
});

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);
});

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);
});

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
});

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.

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 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);
});

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.

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 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);
});