Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface TopicViews

Topic view feature.

This feature allows a client session to manage topic views.

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 RemoteServers 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 path prefix of 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 a session as follows:

const topicViews = session.topicViews;
since

6.3

Hierarchy

  • TopicViews

Index

Methods

Methods

createTopicView

  • Create a new named topic view.

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

    Parameters

    • name: string

      the name of the view

    • specification: string

      the specification of the view using the DSL

    Returns Result<TopicView>

    a Result that completes when a response is received from the server, returning the topic view created by the operation.

    If the task fails, the Result will resolve with an error. Common reasons for failure, include:

    • the specification is invalid;
    • the cluster was repartitioning;
    • the calling session does not have MODIFY_TOPIC_VIEW permission or appropriate path prefix permissions;
    • the session is closed.
    • IllegalArgumentError if the name is empty
    • NullValueError – if any of the arguments are null or undefined

getTopicView

  • Get a named Topic View.

    If the named view does not exist the Result will resolve with null result.

    Parameters

    • name: string

      the name of the view

    Returns Result<TopicView | null>

    a Result that resolves when a response is received from the server, returning a named view if it exists

    If the task fails, the Result will resolve with an Error. Common reasons for failure include:

    • the operation failed due to a transient cluster error;
    • the calling session does not have READ_TOPIC_VIEW permission or appropriate path prefix permissions;
    • the session is closed.
    • NullValueError – if the name is nullorundefined`

listTopicViews

  • List all the topic views that have been created.

    Returns Result<TopicView[]>

    a Result that resolves when a response is received from the server, returning a list of views sorted by their creation order.

    If the task fails, the Result will resolve with an Error. Common reasons for failure include:

    • the cluster was repartitioning;
    • the calling session does not have READ_TOPIC_VIEW permission or appropriate path prefix permissions;
    • the session is closed.

removeTopicView

  • removeTopicView(name: string): Result<void>

  • Remove a named topic view if it exists.

    If the named view does not exist the completable future will complete successfully.

    Parameters

    • name: string

      the name of the view

    Returns Result<void>

    a Result that resolves when a response is received from the server.

    If the task fails, the Result will resolve with an Error. Common reasons for failure include:

    • the cluster was repartitioning;
    • the calling session does not have MODIFY_TOPIC_VIEW permission or appropriate path prefix permissions;
    • the session is closed.
    • NullValueError – if the name is nullorundefined`