Table of Contents

Interface ITopicViews

Namespace
PushTechnology.ClientInterface.Client.Features
Assembly
Diffusion.Client.dll

This feature allows a client session to manage topic views.

public interface ITopicViews : IFeature
Inherited Members

Remarks

A topic view maps one part of a server's topic tree to another. It dynamically creates a set of reference topics from a set of source topics, based on a declarative topic view specification. The capabilities of topic views range from simple mirroring of topics within the topic tree to advanced capabilities including publication of partial values, expanding a single topic value into many topics, changing topic values, inserting values from other topics, throttling the rate of publication, and applying a fixed delay to the publication.

A topic view can also map topics from another server (in a different cluster). This capability is referred to as 'remote topic views'. The view can specify the server that the source topics are hosted on in terms of a remote server (see IRemoteServers for details of how to create and maintain remote servers).

Each reference topic has a single source topic and has the same topic type as its source topic. Reference topics are read-only (they cannot be updated), nor can they be created or removed directly. Otherwise, they behave just like standard topics. A client session can subscribe to a reference topic, and can fetch the reference topic's current value if it has one.

The source topics of a topic view are defined by a topic selector. One or more reference topics are created for each source topic, according to the topic view. If a source topic is removed, reference topics that are derived from it will automatically be removed. If a topic is added that matches the source topic selector of a topic view, corresponding reference topics will be created. Removing a topic view will remove all of its reference topics.

Topic view specifications

Topic views are specified using a Domain Specific Language (DSL) which provides many powerful features for manipulating topic data. For a full and detailed description of the topic views DSL see the user manual.

The following is a simple topic view specification that mirrors all topics below the path a to reference topics below the path b. 

map ?a// to b/<path(1)>

A topic view with this specification will map a source topic at the path a/x/y/z to a reference topic at the path b/x/y/z. The specification is simple, so the reference topic will exactly mirror the source topic. Other topic views features allow a single topic to be mapped to many reference topics and have the data transformed in the process.

Topic view persistence and replication

Reference topics are neither replicated nor persisted. They are created and removed based on their source topics. However, topic views are replicated and persisted. A server that restarts will restore topic views during recovery. Each topic view will then create reference topics based on the source topics that have been recovered.

The server records all changes to topic views in a persistent store. Topic views are restored if the server is started.

If a server belongs to a cluster, topic views (and remote servers) will be replicated to each server in the cluster. Topic views are evaluated locally within a server. Replicated topic views that select non-replicated source topics can create different reference topics on each server in the cluster. When remote topic views are in use, each server in the cluster will make a connection to the specified remote server and will separately manage their remote topic views.

A view with a delay clause uses temporary storage to record delayed events. If there is a high volume of updates, temporary per-server disk files will be used to save server memory​. The storage is per-server, and does not survive server restart. When a server is started, no data will be published by a view with a delay clause until the delay time has expired.

Access control

The following access control restrictions are applied:

  • To list the topic views, a session needs the READ_TOPIC_VIEWS global permission.
  • To create, replace, or remove a topic view, a session needs the MODIFY_TOPIC_VIEWS global permission and SELECT_TOPIC permission for the source topic selector.
  • Each topic view records the principal and security roles of the session that created it as the topic view security context. When a topic view is evaluated, this security context is used to constrain the creation of reference topics. A reference topic will only be created if the security context has READ_TOPIC permission for the source topic path, and MODIFY_TOPIC permission for the reference topic path. The topic view security context is copied from the creating session at the time the topic view is created or replaced, and is persisted with the topic view. The topic view security context is not updated if the roles associated with the session are changed.

Accessing the feature

This feature may be obtained from an ISession as follows: 

var topicViews = session.TopicViews;

This feature is also extended by the ITopics feature. This means it is possible to use the methods described here through the ITopics feature.

Added in version 6.3.

Methods

CreateTopicViewAsync(string, string)

Create a new named topic view.

Task<ITopicView> CreateTopicViewAsync(string name, string specification)

Parameters

name string

The name of the view.

specification string

The specification of the topic view.

Returns

Task<ITopicView>

The Task representing the current operation.

Remarks

If a view with the same name already exists the new view will update the existing view.

If the operation completes successfully, the Task result will be a ITopicView instance.

Exceptions

ArgumentNullException

The name or specification is null.

ArgumentException

The name string is empty.

InvalidTopicViewException

The supplied specification is invalid. Thrown by the returned Task.

SessionSecurityException

The calling session does not have MODIFY_TOPIC_VIEWS permission or appropriate path prefix permissions. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

ClusterRoutingException

A transient cluster error occurred. Thrown by the returned Task.

See Also

CreateTopicViewAsync(string, string, CancellationToken)

Create a new named topic view.

Task<ITopicView> CreateTopicViewAsync(string name, string specification, CancellationToken cancellationToken)

Parameters

name string

The name of the view.

specification string

The specification of the topic view.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<ITopicView>

The Task representing the current operation.

Remarks

The topic view name cannot be empty.

If a view with the same name already exists the new view will update the existing view.

If the operation completes successfully, the Task result will be a ITopicView instance.

Exceptions

ArgumentNullException

The name or specification is null.

ArgumentException

The name string is empty.

InvalidTopicViewException

The supplied specification is invalid. Thrown by the returned Task.

SessionSecurityException

The calling session does not have MODIFY_TOPIC_VIEWS permission or appropriate path prefix permissions. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

ClusterRoutingException

A transient cluster error occurred. Thrown by the returned Task.

GetTopicViewAsync(string)

Get a named Topic View.

Task<ITopicView> GetTopicViewAsync(string name)

Parameters

name string

The name of the view.

Returns

Task<ITopicView>

The Task representing the current operation.

Remarks

If the named view does not exist the Task will complete successfully with a null result.

If the operation completes successfully, the Task result will be a named ITopicView if it exists.

Exceptions

ArgumentNullException

The name is null.

ArgumentException

The name string is empty.

ClusterRoutingException

A transient cluster error occurred. Thrown by the returned Task.

SessionSecurityException

The calling session does not have READ_TOPIC_VIEWS permission or appropriate path prefix permissions. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

GetTopicViewAsync(string, CancellationToken)

Get a named Topic View.

Task<ITopicView> GetTopicViewAsync(string name, CancellationToken cancellationToken)

Parameters

name string

The name of the view.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<ITopicView>

The Task representing the current operation.

Remarks

If the named view does not exist the Task will complete successfully with a null result.

If the operation completes successfully, the Task result will be a named ITopicView if it exists.

Exceptions

ArgumentNullException

The name is null.

ArgumentException

The name string is empty.

ClusterRoutingException

A transient cluster error occurred. Thrown by the returned Task.

SessionSecurityException

The calling session does not have READ_TOPIC_VIEWS permission or appropriate path prefix permissions. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

ListTopicViewsAsync()

List all of the topic views that have been created.

Task<IReadOnlyCollection<ITopicView>> ListTopicViewsAsync()

Returns

Task<IReadOnlyCollection<ITopicView>>

The Task representing the current operation.

Remarks

If the operation completes successfully, the Task result will be a IReadOnlyCollection<T> instance containing all topic views.

Exceptions

SessionSecurityException

The calling session does not have READ_TOPIC_VIEWS permission. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

See Also

ListTopicViewsAsync(CancellationToken)

List all of the topic views that have been created.

Task<IReadOnlyCollection<ITopicView>> ListTopicViewsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<IReadOnlyCollection<ITopicView>>

The Task representing the current operation.

Remarks

If the operation completes successfully, the Task result will be a IReadOnlyCollection<T> instance containing all topic views.

Exceptions

SessionSecurityException

The calling session does not have READ_TOPIC_VIEWS permission. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

RemoveTopicViewAsync(string)

Remove a named topic view if it exists.

Task<object> RemoveTopicViewAsync(string name)

Parameters

name string

The name of the view.

Returns

Task<object>

The Task representing the current operation.

Remarks

If the named view does not exist the Task will complete successfully.

If the task completes successfully, the Task result will be null.

Exceptions

ArgumentNullException

The name is null.

ArgumentException

The name string is empty.

SessionSecurityException

The calling session does not have MODIFY_TOPIC_VIEWS permission. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

ClusterRoutingException

A transient cluster error occurred. Thrown by the returned Task.

See Also

RemoveTopicViewAsync(string, CancellationToken)

Remove a named topic view if it exists.

Task<object> RemoveTopicViewAsync(string name, CancellationToken cancellationToken)

Parameters

name string

The name of the view.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<object>

The Task representing the current operation.

Remarks

If the named view does not exist the Task will complete successfully.

If the task completes successfully, the Task result will be null.

Exceptions

ArgumentNullException

The name is null.

ArgumentException

The name string is empty.

SessionSecurityException

The calling session does not have MODIFY_TOPIC_VIEWS permission. Thrown by the returned Task.

SessionClosedException

The calling session is closed. Thrown by the returned Task.

ClusterRoutingException

A transient cluster error occurred. Thrown by the returned Task.