Diffusion C API  6.7.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
session-trees.h File Reference

Session Trees feature. More...

Data Structures

struct  diffusion_session_trees_put_branch_mapping_table_params_s
 Structure supplied when issuing a diffusion_session_trees_put_branch_mapping_table call. More...
 
struct  diffusion_session_trees_get_session_tree_branches_params_s
 Structure supplied when issuing a diffusion_session_trees_get_session_tree_branches call. More...
 
struct  diffusion_session_trees_get_branch_mapping_table_params_s
 Structure supplied when issuing a diffusion_session_trees_get_branch_mapping_table call. More...
 

Typedefs

typedef struct
DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T 
DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T
 Opaque Branch Mapping Table Builder struct.
 
typedef struct
DIFFUSION_BRANCH_MAPPING_TABLE_T 
DIFFUSION_BRANCH_MAPPING_TABLE_T
 Opaque Branch Mapping Table struct.
 
typedef struct
DIFFUSION_BRANCH_MAPPING_T 
DIFFUSION_BRANCH_MAPPING_T
 Opaque Branch Mapping struct.
 
typedef int(* branch_mapping_table_set_cb )(void *context)
 callback when branch mapping table has been set on the server More...
 
typedef int(* get_session_tree_branches_cb )(const LIST_T *session_tree_branches, void *context)
 callback when branch mapping table has been set on the server More...
 
typedef int(* get_branch_mapping_table_cb )(const DIFFUSION_BRANCH_MAPPING_TABLE_T *table, void *context)
 callback when branch mapping table has been retrieved from the server More...
 
typedef struct
diffusion_session_trees_put_branch_mapping_table_params_s 
DIFFUSION_SESSION_TREES_PUT_BRANCH_MAPPING_TABLE_PARAMS_T
 Structure supplied when issuing a diffusion_session_trees_put_branch_mapping_table call.
 
typedef struct
diffusion_session_trees_get_session_tree_branches_params_s 
DIFFUSION_SESSION_TREES_GET_SESSION_TREE_BRANCHES_PARAMS_T
 Structure supplied when issuing a diffusion_session_trees_get_session_tree_branches call.
 
typedef struct
diffusion_session_trees_get_branch_mapping_table_params_s 
DIFFUSION_SESSION_TREES_GET_BRANCH_MAPPING_TABLE_PARAMS_T
 Structure supplied when issuing a diffusion_session_trees_get_branch_mapping_table call.
 

Functions

DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_Tdiffusion_branch_mapping_table_builder_init ()
 Initialise a new branch mapping table builder. More...
 
DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_Tdiffusion_branch_mapping_table_builder_reset (DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T *builder)
 Reset the stored branch mappings in the branch mapping table builder. More...
 
DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_Tdiffusion_branch_mapping_table_builder_add_branch_mapping (DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T *builder, char *session_filter, char *topic_tree_branch)
 Adds a new branch mapping with the specified values. More...
 
DIFFUSION_BRANCH_MAPPING_TABLE_Tdiffusion_branch_mapping_table_builder_create_table (DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T *builder, char *session_tree_branch)
 Creates a branch mapping table for the specified session tree branch. More...
 
void diffusion_branch_mapping_table_builder_free (DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T *builder)
 Free a branch mapping table builder. More...
 
void diffusion_branch_mapping_table_free (DIFFUSION_BRANCH_MAPPING_TABLE_T *table)
 Free a branch mapping table. More...
 
char * diffusion_branch_mapping_table_get_session_tree_branch (DIFFUSION_BRANCH_MAPPING_TABLE_T *table)
 Get the session tree branch from a branch mapping table. More...
 
LIST_Tdiffusion_branch_mapping_table_get_branch_mappings (DIFFUSION_BRANCH_MAPPING_TABLE_T *table)
 Get the branch mappings from a branch mapping table. More...
 
void diffusion_branch_mapping_table_free_branch_mappings (LIST_T *branch_mappings)
 Free a list containing branch mappings. More...
 
char * diffusion_branch_mapping_get_session_filter (DIFFUSION_BRANCH_MAPPING_T *mapping)
 Get the session filter from a branch mapping. More...
 
char * diffusion_branch_mapping_get_topic_tree_branch (DIFFUSION_BRANCH_MAPPING_T *mapping)
 Get the topic tree branch from a branch mapping. More...
 
bool diffusion_session_trees_put_branch_mapping_table (SESSION_T *session, const DIFFUSION_SESSION_TREES_PUT_BRANCH_MAPPING_TABLE_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Create or replace a branch mapping table. More...
 
bool diffusion_session_trees_get_session_tree_branches (SESSION_T *session, const DIFFUSION_SESSION_TREES_GET_SESSION_TREE_BRANCHES_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Retrieve the session tree branches of the server's branch mapping tables. More...
 
bool diffusion_session_trees_get_branch_mapping_table (SESSION_T *session, const DIFFUSION_SESSION_TREES_GET_BRANCH_MAPPING_TABLE_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Retrieve a branch mapping table from the server. More...
 

Detailed Description

Session Trees feature.

This feature allows a client session to configure session trees.

A session tree is a virtual view of the topic tree presented to a session by fetch and subscription operations. Custom session trees for different sessions can be configured using declarative rules maintained by the server to meet data security, data optimisation, or personalisation and localisation requirements. Each session can be presented with a unique session tree based on its session properties.

A session tree is produced by applying branch mappings to the topic tree. Branch mappings are organised into branch mapping tables. Each branch mapping table is assigned to a unique path – the session tree branch.

A session tree is composed of session paths. Each session path is mapped via the branch mapping tables to a unique topic path.

A branch mapping table is an ordered list of (session filter, topic tree branch) pairs. For example, the branch mapping table for the session tree branch market/prices might be:

Session filter                           Topic tree branch
==============                           =================
USER_TIER is '1' or $Country is 'DE'     backend/discounted_prices
USER_TIER is '2'                         backend/standard_prices
$Principal is ''                         backend/delayed_prices

With this configuration, if an unauthenticated session (one that matches the $Principal is '' session filter) subscribes to the session path market/prices/X, and there is a topic bound to the topic path backend/delayed_prices/X, the subscription will complete. The session will receive a subscription notification under the session path market/prices/X, together with the topic properties and the value of the topic. The session is unaware that the data originates from a topic bound to a different topic path. If no topic is bound to backend/delayed_prices/X, the subscription will not resolve and the session will receive no data, even if there is a topic bound to market/prices/X.

Session trees complement the data transformation capabilities of topic views. In our example, the time delayed time feed at backend/delayed_prices could be maintained by a topic view using the delay by clause.

Branch mappings are persisted by the server and shared across a cluster, in a similar manner to topic views, security stores, and metric collectors. Branch mappings are editable using this feature, and via the management console.

For a given session and session path, at most one branch mapping applies. The applicable branch mapping is chosen as follows:

  • Each branch mapping table with session tree branch that is a prefix of the session path is considered. For a given table, the first branch mapping with a session filter that matches the session's properties is the one that applies. A branch mapping table may have no applicable branch mappings for a session.
  • If there are several such branch mapping tables with a branch mapping that for the session, the one with the longest prefix of the session path applies.
  • If no branch mapping table has a branch mapping for the session, the session path is translated to the identical topic path.

Access control

To subscribe to or fetch from a session path, a session must be granted the appropriate path permission to the session path for the operation PATH_PERMISSION_SELECT_TOPIC, or PATH_PERMISSION_READ_TOPIC). The session doesn't require any permissions to the topic path of the topic providing the data.

To create or replace branch mappings, a session needs the PATH_PERMISSION_MODIFY_TOPIC path permission for the session tree branch of the branch mapping table, PATH_PERMISSION_EXPOSE_BRANCH path permission for the topic tree branch of each branch mapping, and (if an existing table with the same session tree branch is being replaced) PATH_PERMISSION_EXPOSE_BRANCH permission for each branch mapping of existing table.

To retrieve a branch mapping table, a session needs the PATH_PERMISSION_READ_TOPIC path permission for its session tree branch.

Since
6.7

Typedef Documentation

typedef int(* branch_mapping_table_set_cb)(void *context)

callback when branch mapping table has been set on the server

Parameters
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* get_branch_mapping_table_cb)(const DIFFUSION_BRANCH_MAPPING_TABLE_T *table, void *context)

callback when branch mapping table has been retrieved from the server

Parameters
tableThe branch mapping table.
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* get_session_tree_branches_cb)(const LIST_T *session_tree_branches, void *context)

callback when branch mapping table has been set on the server

Parameters
session_tree_branchesA list of session tree branches.
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

Function Documentation

char* diffusion_branch_mapping_get_session_filter ( DIFFUSION_BRANCH_MAPPING_T mapping)

Get the session filter from a branch mapping.

Parameters
tableThe branch mapping
Returns
the session filter of the branch mapping if valid or NULL otherwise.
char* diffusion_branch_mapping_get_topic_tree_branch ( DIFFUSION_BRANCH_MAPPING_T mapping)

Get the topic tree branch from a branch mapping.

Parameters
tableThe branch mapping
Returns
the topic tree branch of the branch mapping if valid or NULL otherwise.
DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T* diffusion_branch_mapping_table_builder_add_branch_mapping ( DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T builder,
char *  session_filter,
char *  topic_tree_branch 
)

Adds a new branch mapping with the specified values.

Parameters
builderthe branch mapping table builder.
session_filterthe session filter.
topic_tree_branchthe topic tree branch.
Returns
the branch mapping table builder
DIFFUSION_BRANCH_MAPPING_TABLE_T* diffusion_branch_mapping_table_builder_create_table ( DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T builder,
char *  session_tree_branch 
)

Creates a branch mapping table for the specified session tree branch.

Parameters
session_tree_branchthe session filter.
topic_tree_branchthe .
builderthe branch mapping table builder.
Returns
the branch mapping table builder
void diffusion_branch_mapping_table_builder_free ( DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T builder)

Free a branch mapping table builder.

Parameters
builderThe branch mapping table builder.
DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T* diffusion_branch_mapping_table_builder_init ( )

Initialise a new branch mapping table builder.

diffusion_branch_mapping_table_builder_free should be called on this pointer when no longer needed.

Returns
the branch mapping table builder
DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T* diffusion_branch_mapping_table_builder_reset ( DIFFUSION_BRANCH_MAPPING_TABLE_BUILDER_T builder)

Reset the stored branch mappings in the branch mapping table builder.

Parameters
builderthe branch mapping table builder.
Returns
the branch mapping table builder
void diffusion_branch_mapping_table_free ( DIFFUSION_BRANCH_MAPPING_TABLE_T table)

Free a branch mapping table.

Parameters
tableThe branch mapping table.
void diffusion_branch_mapping_table_free_branch_mappings ( LIST_T branch_mappings)

Free a list containing branch mappings.

Parameters
branch_mappingsThe list containing the branch mappings
LIST_T* diffusion_branch_mapping_table_get_branch_mappings ( DIFFUSION_BRANCH_MAPPING_TABLE_T table)

Get the branch mappings from a branch mapping table.

Parameters
tableThe branch mapping table
Returns
a list containing DIFFUSION_BRANCH_MAPPING_T elements if valid or NULL otherwise.
char* diffusion_branch_mapping_table_get_session_tree_branch ( DIFFUSION_BRANCH_MAPPING_TABLE_T table)

Get the session tree branch from a branch mapping table.

Parameters
tableThe branch mapping table.
Returns
the session tree branch if present, NULL otherwise.
bool diffusion_session_trees_get_branch_mapping_table ( SESSION_T session,
const DIFFUSION_SESSION_TREES_GET_BRANCH_MAPPING_TABLE_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Retrieve a branch mapping table from the server.

If there is no branch mapping table at the given session tree branch, this method will return an empty branch mapping table.

Parameters
sessionThe current session. If NULL, this function returns immediately.
paramsParameter structure describing the session tree branch name and the callbacks to be invoked.
api_errorPopulated on API error. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_session_trees_get_session_tree_branches ( SESSION_T session,
const DIFFUSION_SESSION_TREES_GET_SESSION_TREE_BRANCHES_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Retrieve the session tree branches of the server's branch mapping tables.

The results will only include the session tree branches of branch mapping tables that have at least one branch mapping and for which the calling session has PATH_PERMISSION_READ_TOPIC path permission for the session tree branch.

Individual branch mapping tables can be retrieved using diffusion_session_trees_get_branch_mapping_table.

Parameters
sessionThe current session. If NULL, this function returns immediately.
paramsParameter structure describing the callbacks to be invoked.
api_errorPopulated on API error. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_session_trees_put_branch_mapping_table ( SESSION_T session,
const DIFFUSION_SESSION_TREES_PUT_BRANCH_MAPPING_TABLE_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Create or replace a branch mapping table.

The server ensures that a session tree branch has at most one branch mapping table. Putting a new branch mapping table will replace any previous branch mapping table with the same session tree branch. To remove all branch mappings for a session tree branch, put an empty branch mapping table.

Parameters
sessionThe current session. If NULL, this function returns immediately.
paramsParameter structure describing the branch mapping table and the callbacks to be invoked.
api_errorPopulated on API error. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.