Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface ClientControl

Client control feature.

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

Example:

var clients = session.clients;

Hierarchy

  • ClientControl

Index

Properties

SessionEventType

SessionEventType: SessionEventType

Methods

changeRoles

  • changeRoles(sessions: SessionId | string, rolesToRemove: string[] | Set<string>, rolesToAdd: string[] | Set<string>): Result<number>
  • 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.

    since

    6.3

    Parameters

    • sessions: SessionId | string

      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.

    • rolesToRemove: string[] | Set<string>

      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.

    • rolesToAdd: string[] | Set<string>

      a set of roles to be added to the session. If one or more roles from the list are already assigned, they are ignored.

    Returns Result<number>

    a Result 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 Result fails with an Error. Common reasons for failure include:

    • the calling session does not have MODIFY_SESSION and VIEW_SESSION permission;
    • a SessionId was supplied and there is no session with the given sessionId;
    • a filter string was supplied that could not be parsed
    • the calling session is closed.

close

  • close(sessions: string | SessionId): Result<number>
  • 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
    });

    Parameters

    • sessions: string | SessionId

      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.

    Returns Result<number>

    a Result that resolves to the number of affected sessions

getSessionProperties

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

    Parameters

    • session: string | SessionId
    • Optional properties: string[]

      specifies the keys of the property values required.

    Returns Result<SessionProperties>

    a Result for this operation

setConflated

  • setConflated(sessions: SessionId | string, conflated: boolean): Result<number>
  • 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.

    since

    6.5

    Parameters

    • sessions: SessionId | string

      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.

    • conflated: boolean

    Returns Result<number>

    a Result that resolves to the number of affected sessions

    If the conflation policy was updated for the identified session, the Result will resolve successfully.

    Otherwise, the Result fails with an Error. Common reasons for failure include:

    • the identified session was closed before the response was delivered;
    • the calling session does not have MODIFY_SESSION and VIEW_SESSION permissions;
    • the calling session is closed.

setSessionProperties

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

    Parameters

    • session: string | SessionId

      identifies the client session

    • properties: SessionProperties | Map<string, string | null>

      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).

    Returns Result<SessionProperties>

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

setSessionPropertiesByFilter

  • setSessionPropertiesByFilter(filter: string, properties: SessionProperties | Map<string, string | null>): Result<number>
  • 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);
    });

    Parameters

    • filter: string

      session filter

    • properties: SessionProperties | Map<string, string | null>

      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).

    Returns Result<number>

    a Result 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:

setSessionPropertiesListener

  • 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.

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

    Parameters

    Returns Result<void>

    a Result for this operation.

subscribe

  • 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.

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

    Parameters

    • session: string | SessionId

      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.

    • selector: string | TopicSelector | Array<string | TopicSelector>

      the Topic Selector to subscribe to

    Returns Result<number | void>

    a Result for this operation. If subscribing with a session filter, the success callback will be given the number of sessions selected by the filter

unsubscribe

  • 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.

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

    Parameters

    • session: string | SessionId

      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.

    • selector: string | TopicSelector | Array<string | TopicSelector>

      the Topic Selector to unsubscribe from

    Returns Result<number | void>

    a Result for this operation. If unsubscribing with a session filter, the success callback will be given the number of sessions selected by the filter