Session filtering
Session filters enable you to address a set of connected client sessions on the Diffusion??? server based on their session properties.
Using Session Filters
Session filters are query expressions for session properties. They can be used to address a set of sessions based on their session properties. For example, it is possible to send a message to all sessions that satisfy a specified filter. Session filters are parsed and evaluated at the server.
(Department is "Accounts" or Department is "Payroll") and Status is "Closed"
not Department is "Payroll"
not (Department is "Payroll" or Department is "Accounts")
An equality clause has the form key operator value where key is the name of a session property and value is the property value. The supported operators are is or eq, both of which mean "equals", and ne which means "does not equal". Values are strings enclosed within single or double quotes.
The matches operator tests whether the value of a session property matches the given regular expression. The regular expression is a string enclosed within single or double quotes.
Special characters (, ' or \) can be included within the value by preceding with the escape character \.
A utility method (Diffusion.escape(String) in the Java SDK) can be used to insert escape characters into a value.
The unary has operator is for querying whether a particular property is present. This is useful for checking if a user-defined property or an optional fixed property has been set.
The unary hasRoles operator is for querying the $Roles session property. A hasRoles clause has the form hasRoles "role1" "role2" ... "roleN". The clause will match sessions that have all the specified authorisation roles. Each role is a string enclosed within either single or double quotes. Roles can be space or comma separated.
The $Roles session property can also be queried with an equality clause, for example, $Roles eq '"admin" "client"', but the hasRoles clause is usually more convenient. An equality clause will match sessions that have exactly the listed roles. In contrast, a hasRoles clause will match any sessions with the listed roles, regardless of whether they have other roles. The equality clause requires the value to be in the canonical form produced by the rolesToString utility method (Diffusion.rolesToString(Set) in the Java SDK).
The in operator tests whether the value of a session property belongs to a fixed set. For example, $COUNTRY in 'UK', 'DE', 'FR' matches sessions from a set of countries: Germany, France, and the UK.
The lists provided to in and hasRoles can optionally use square brackets and commas as delimiters. For example $Country in ['UK','DE','FR'].
The all clause matches all sessions.
All operators are case insensitive. So hasroles, HASROLES, and hasRoles are all equivalent
Examples
$Principal IS 'Ellington'
$Environment matches '^(ANDROID.*|iOS.*)'
$Transport EQ 'WEBSOCKET'
$Country NE 'GB'
Location IS "San Jose"
Status EQ 'Active'
Tier NE 'Premium'
$COUNTRY in ['UK', 'DE', 'FR']
has Address
hasRoles ["operator", "trading desk"]
$Principal IN ['Fitzgerald' 'Gillespie' 'Hancock']
$Transport EQ 'WEBSOCKET' AND $Country IS 'FR' AND Status EQ 'Active'
$Country EQ 'US' AND NOT ($Principal IS 'Monk' OR $Principal IS 'Peterson')
NOT (Status IS 'Inactive' AND Tier IS 'Free')
all