Just a second...

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.

A session filter expression consists of either a single clause, or multiple clauses connected by the binary operators and and or. The and operator takes precedence over or but parentheses can be used to override the precedence. For example:
(Department is "Accounts" or Department is "Payroll") and Status is "Closed"
The unary not operator can be used to negate the following clause or an expression within parentheses:
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

Filter by sessions that connect with the principal Ellington:
$Principal IS 'Ellington'
Filter by sessions whose environment property starts with Android or iOS:
$Environment matches '^(ANDROID.*|iOS.*)'
Filter by sessions that connect to the Diffusion server using WebSocket :
$Transport EQ 'WEBSOCKET'
Filter by sessions that are not located in the United Kingdom:
$Country NE 'GB'
Filter by sessions that have the user-defined property Location set to San Jose:
Location IS "San Jose"
Filter by sessions that have the user-defined property Status set to Active:
Status EQ 'Active'
Filter by sessions that do not have the user-defined property Tier set to Premium:
Tier NE 'Premium'
Filter by sessions that are located in one of a set of countries:
$COUNTRY in ['UK', 'DE', 'FR']
Filter by sessions that have the Address property set:
has Address
Filter by sessions that have either of the specified security roles:
hasRoles ["operator", "trading desk"]
Filter by sessions that connect with one of the principals Fitzgerald, Gillespie, or Hancock:
$Principal IN ['Fitzgerald' 'Gillespie' 'Hancock']
Filter by sessions that connect to the Diffusion server using WebSocket and are located in France and have the user-defined property Status set to Active:
$Transport EQ 'WEBSOCKET' AND $Country IS 'FR' AND Status EQ 'Active'
Filter by sessions that are located in the United States, but do not connect with either of the principals Monk or Peterson:
$Country EQ 'US' AND NOT ($Principal IS 'Monk' OR $Principal IS 'Peterson')
Filter by sessions excluding those that have both the user-defined property Status set to Inactive and the user-defined property Tier set to Free:
NOT (Status IS 'Inactive' AND Tier IS 'Free')
Select all sessions:
all