public interface SessionTrees extends Feature
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:
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
(SELECT_TOPIC
, or
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
MODIFY_TOPIC
path permission for the
session tree branch of the branch mapping table,
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)
EXPOSE_BRANCH
permission for each branch
mapping of existing table.
To retrieve a branch mapping table, a session needs the
READ_TOPIC
path permission for its session
tree branch.
This feature may be obtained from a session
as follows:
SessionTrees sessionTrees = session.feature(SessionTrees.class);
This feature is also extended by the Topics
feature. This
means is it possible to use the methods described here through the
Topics
feature.
Modifier and Type | Interface and Description |
---|---|
static interface |
SessionTrees.BranchMapping
A session tree branch mapping.
|
static interface |
SessionTrees.BranchMappingTable
A session tree branch mapping table.
|
static class |
SessionTrees.InvalidBranchMappingException
Exception indicating an invalid
SessionTrees.BranchMapping or
SessionTrees.BranchMappingTable . |
Modifier and Type | Method and Description |
---|---|
CompletableFuture<SessionTrees.BranchMappingTable> |
getBranchMappingTable(String sessionTreeBranch)
Retrieve a branch mapping table from the server.
|
CompletableFuture<List<String>> |
listSessionTreeBranchesWithMappings()
Retrieve the session tree branches of the server's branch mapping tables.
|
CompletableFuture<?> |
putBranchMappingTable(SessionTrees.BranchMappingTable branchMappingTable)
Create or replace a branch mapping table.
|
getSession
CompletableFuture<?> putBranchMappingTable(SessionTrees.BranchMappingTable branchMappingTable)
The server ensures that there is at most one branch mapping table for a session tree branch. 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.
branchMappingTable
- the new tableIf the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
Otherwise, the CompletableFuture will complete exceptionally with
a CompletionException
. Common reasons for failure, listed
by the exception reported as the
cause
, include:
SessionTrees.InvalidBranchMappingException
– if
branchMappingTable or one of its branch mappings is invalid;
PermissionsException
– if the calling
session does not have the MODIFY_TOPIC
permission for the session tree branch of the
branch mapping table, EXPOSE_BRANCH
permission for each branch mapping of
branchMappingTable, and (if there is an existing table for the
session tree branch) EXPOSE_BRANCH
permission for each branch mapping of existing
table;
ClusterRoutingException
– if the operation
failed due to a transient cluster error;
SessionClosedException
– if the session is
closed.
CompletableFuture<List<String>> listSessionTreeBranchesWithMappings()
READ_TOPIC
path permission
for the session tree branch.
Individual branch mapping tables can be retrieved using
getBranchMappingTable(String)
.
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
SessionClosedException
– if the session is
closed.
CompletableFuture<SessionTrees.BranchMappingTable> getBranchMappingTable(String sessionTreeBranch)
If there is no branch mapping table at the given session tree branch, this method will return an empty branch mapping table.
sessionTreeBranch
- the session tree branch that identifies the
branch mapping table
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
PermissionsException
– if the calling
session does not have the READ_TOPIC
permission for sessionTreeBranch;
SessionClosedException
– if the session is
closed.
Copyright © 2024 DiffusionData Ltd. All Rights Reserved.