topic-views.h File Reference

Allows a client session to manage topic views. More...

Data Structures
struct	diffusion_create_topic_view_params_s
	Structure describing a request to create a topic view. More...
struct	diffusion_topic_views_list_params_s
	Structure describing a request to list topic views. More...
struct	diffusion_remove_topic_view_params_s
	Structure describing a request to remove a topic view. More...
struct	diffusion_get_topic_view_params_s
	Structure describing a request to get a topic view. More...

Typedefs
typedef struct DIFFUSION_TOPIC_VIEW_T	DIFFUSION_TOPIC_VIEW_T
	Opaque topic view struct.
typedef int(*	on_topic_view_created_cb) (const DIFFUSION_TOPIC_VIEW_T *topic_view, void *context)
	Callback when a topic view has successfully been created.
typedef int(*	on_topic_view_response_cb) (void *context)
	Callback when a response is received from the server regarding a topic view operation.
typedef int(*	on_topic_view_retrieved_cb) (const DIFFUSION_TOPIC_VIEW_T *topic_view, void *context)
	Callback when a topic view has successfully been retrieved.
typedef int(*	on_topic_views_list_cb) (const LIST_T *topic_views, void *context)
	Callback when a response is received from the server regarding a diffusion_topic_views_list_topic_views operation.
typedef struct diffusion_create_topic_view_params_s	DIFFUSION_CREATE_TOPIC_VIEW_PARAMS_T
	Structure describing a request to create a topic view.
typedef struct diffusion_topic_views_list_params_s	DIFFUSION_TOPIC_VIEWS_LIST_PARAMS_T
	Structure describing a request to list topic views.
typedef struct diffusion_remove_topic_view_params_s	DIFFUSION_REMOVE_TOPIC_VIEW_PARAMS_T
	Structure describing a request to remove a topic view.
typedef struct diffusion_get_topic_view_params_s	DIFFUSION_GET_TOPIC_VIEW_PARAMS_T
	Structure describing a request to get a topic view.

Functions
char *	diffusion_topic_view_get_name (const DIFFUSION_TOPIC_VIEW_T *topic_view)
	Return a memory allocated copy of the topic view's name.
char *	diffusion_topic_view_get_specification (const DIFFUSION_TOPIC_VIEW_T *topic_view)
	Return a memory allocated copy of the topic view's specification.
SET_T *	diffusion_topic_view_get_roles (const DIFFUSION_TOPIC_VIEW_T *topic_view)
	Return a memory allocated SET_T of the topic view's roles.
DIFFUSION_TOPIC_VIEW_T *	diffusion_topic_view_dup (const DIFFUSION_TOPIC_VIEW_T *topic_view)
	Returns a memory allocated copy of a DIFFUSION_TOPIC_VIEW_T.
void	diffusion_topic_view_free (DIFFUSION_TOPIC_VIEW_T *topic_view)
	Free a memory allocated DIFFUSION_TOPIC_VIEW_T
bool	diffusion_topic_views_create_topic_view (SESSION_T *session, const DIFFUSION_CREATE_TOPIC_VIEW_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Create a new named topic view.
bool	diffusion_topic_views_list_topic_views (SESSION_T *session, const DIFFUSION_TOPIC_VIEWS_LIST_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	List all the topic views that have been created.
bool	diffusion_topic_views_remove_topic_view (SESSION_T *session, const DIFFUSION_REMOVE_TOPIC_VIEW_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Remove a named topic view if it exists.
bool	diffusion_topic_views_get_topic_view (SESSION_T *session, const DIFFUSION_GET_TOPIC_VIEW_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Get a named Topic View.

Detailed Description

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 another topics, throttling the rate of publication, and applying a fixed delay to the publication.

A topic view can even 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 remote servers 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 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, a corresponding reference topic 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.

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.

Typedef Documentation

DIFFUSION_CREATE_TOPIC_VIEW_PARAMS_T

typedef struct diffusion_create_topic_view_params_s DIFFUSION_CREATE_TOPIC_VIEW_PARAMS_T

Structure describing a request to create a topic view.

If the name is empty, the operation will fail.

on_topic_view_created_cb

typedef int(* on_topic_view_created_cb) (const DIFFUSION_TOPIC_VIEW_T *topic_view, void *context)

Callback when a topic view has successfully been created.

Parameters

topic_view	The created topic view.
context	User supplied context.

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

on_topic_view_response_cb

typedef int(* on_topic_view_response_cb) (void *context)

Callback when a response is received from the server regarding a topic view operation.

Parameters

context

User supplied context.

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

on_topic_view_retrieved_cb

typedef int(* on_topic_view_retrieved_cb) (const DIFFUSION_TOPIC_VIEW_T *topic_view, void *context)

Callback when a topic view has successfully been retrieved.

Parameters

topic_view	The retrieved topic view.
context	User supplied context.

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

on_topic_views_list_cb

typedef int(* on_topic_views_list_cb) (const LIST_T *topic_views, void *context)

Callback when a response is received from the server regarding a diffusion_topic_views_list_topic_views operation.

Parameters

topic_views	A LIST_T containing DIFFUSION_TOPIC_VIEW_Ts
context	User supplied context.

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.