TopicViews (Diffusion)

All Superinterfaces:

Feature

All Known Subinterfaces:

Topics
```
public interface TopicViews
extends 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:
```
 TopicViews topicViews = session.feature(TopicViews.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.
Since:

6.3

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`CompletableFuture<TopicView>`	`createTopicView(String name, String specification)` Create a new named topic view.
`CompletableFuture<TopicView>`	`getTopicView(String name)` Get a named Topic View.
`CompletableFuture<List<TopicView>>`	`listTopicViews()` List all the topic views that have been created.
`CompletableFuture<?>`	`removeTopicView(String name)` Remove a named topic view if it exists.

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature
getSession

- Method Detail
  - createTopicView
```
CompletableFuture<TopicView> createTopicView(String name,
                                             String specification)
```
    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 - the name of the view. If the name is empty, the operation will throw an InvalidArgumentException.
    
    specification - the specification of the topic view
    
    Returns:
    a CompletableFuture that completes when a response is received from the server, returning the topic view created by the operation.
    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:
    
    ScriptException – if specification is invalid;
    ClusterRoutingException – if the operation failed due to a transient cluster error;
    PermissionsException – if the calling session does not have MODIFY_TOPIC_VIEW permission or appropriate path prefix permissions;
    SessionClosedException – if the session is closed.
  - listTopicViews
```
CompletableFuture<List<TopicView>> listTopicViews()
```
    List all the topic views that have been created.
    Returns:
    a CompletableFuture that completes when a response is received from the server, returning a list of views sorted by their creation order.
    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:
    
    ClusterRoutingException – if the operation failed due to a transient cluster error;
    PermissionsException – if the calling session does not have READ_TOPIC_VIEW permission or appropriate path prefix permissions;
    SessionClosedException – if the session is closed.
  - getTopicView
```
CompletableFuture<TopicView> getTopicView(String name)
```
    Get a named Topic View.
    If the named view does not exist the completable future will complete successfully with a null result.
    Parameters:
    
    name - the name of the view
    
    Returns:
    a CompletableFuture that completes when a response is received from the server, returning a named view if it exists
    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:
    
    ClusterRoutingException – if the operation failed due to a transient cluster error;
    PermissionsException – if the calling session does not have READ_TOPIC_VIEW permission or appropriate path prefix permissions;
    SessionClosedException – if the session is closed.
  - removeTopicView
```
CompletableFuture<?> removeTopicView(String name)
```
    Remove a named topic view if it exists.
    If the named view does not exist the completable future will complete successfully.
    Parameters:
    
    name - the name of the view
    
    Returns:
    a CompletableFuture that completes when a response is received from the server.
    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:
    
    ClusterRoutingException – if the operation failed due to a transient cluster error;
    PermissionsException – if the calling session does not have MODIFY_TOPIC_VIEW permission or appropriate path prefix permissions;
    SessionClosedException – if the session is closed.

Interface TopicViews

Topic view specifications

Topic view persistence and replication

Access control

Accessing the feature

Method Summary

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

Method Detail

createTopicView

listTopicViews

getTopicView

removeTopicView