Represents a feature that allows a client session to subscribe to topics to receive streamed topic updates and/or fetch the state of topics. More...

Inheritance diagram for PushTechnology.ClientInterface.Client.Features.ITopics:

Public Member Functions
void	AddTopicStream (ITopicSelector topics, ITopicStream stream)
	Adds a topic stream to receive topic updates for topics that match the given PushTechnology.ClientInterface.Client.Topics.ITopicSelector. More...

void	AddTopicStream (string topics, ITopicStream stream)
	Adds a topic stream to receive topic events for all topics that match a given PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression. More...

void	AddStream< TValue > (ITopicSelector topics, IValueStream< TValue > stream)
	Adds a value stream to receive topic events for topics that match a given PushTechnology.ClientInterface.Client.Topics.ITopicSelector and have a value type that matches the specified type. More...

void	AddStream< TValue > (string topics, IValueStream< TValue > stream)
	Adds a value stream to receive topic events for topics that match a given PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression and have a value type that matches the specified type. More...

void	AddFallbackTopicStream (ITopicStream stream)
	Adds a fallback topic stream. More...

void	AddFallbackStream< TValue > (IValueStream< TValue > stream)
	Adds a fallback value stream. More...

void	RemoveStream (Callbacks.IStream stream)
	Removes a stream. More...

void	Subscribe (ITopicSelector topics, ITopicsCompletionCallback callback)
	Requests subscription to topics. More...

void	Subscribe (string topics, ITopicsCompletionCallback callback)
	Requests subscription to topics. More...

void	Subscribe< TContext > (ITopicSelector topics, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Requests subscription to topics. More...

void	Subscribe< TContext > (string topics, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Requests subscription to topics. More...

void	Unsubscribe (ITopicSelector topics, ITopicsCompletionCallback callback)
	Unsubscribes from topics. More...

void	Unsubscribe (string topics, ITopicsCompletionCallback callback)
	Unsubscribes from topics. More...

void	Unsubscribe< TContext > (ITopicSelector topics, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Unsubscribes from topics. More...

void	Unsubscribe< TContext > (string topics, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Unsubscribes from topics. More...

void	Fetch (ITopicSelector topics, IFetchStream callback)
	Fetches the current state of topics. More...

void	Fetch (string topics, IFetchStream callback)
	Fetches the current state of topics. More...

void	Fetch< TContext > (ITopicSelector topics, TContext context, IFetchContextStream< TContext > callback)
	Fetches the current state of topics. More...

void	Fetch< TContext > (string topics, TContext context, IFetchContextStream< TContext > callback)
	Fetches the current state of topics. More...

void	GetTopicDetails (string topicPath, TopicDetailsLevel level, ITopicDetailsCallback callback)
	Gets the details of a given topic. More...

void	GetTopicDetails< TContext > (string topicPath, TopicDetailsLevel level, TContext context, ITopicDetailsContextCallback< TContext > callback)
	Gets the details of a given topic. More...

void	RemoveTopicStream (ITopicStream stream)
	Removes a topic stream. More...

Additional Inherited Members
Properties inherited from PushTechnology.ClientInterface.Client.Features.IFeature
ISession	Session `[get]`
	Get the session that the service is associated with. More...

Detailed Description

Represents a feature that allows a client session to subscribe to topics to receive streamed topic updates and/or fetch the state of topics.

Specifically, the feature provides the ability to:

Subscribe to topics and specify streams to receive updates.
Fetch the current state of topics (even if not subscribed).
Retrieve details of topics - such as their metadata.

Subscription and unsubscription

A session can issue requests to subscribe to topics at any time, even if the topics do not exist at the server. Topic selectors are used on subscription to match against topics at the server. The session will become subscribed to any topics that exist at the server that match the selector (unless they are already subscribed, or the session has insufficient permission). The subscription request is also retained at the server so that if any newly created topics match the selector, the session will then become subscribed to it (unless a subsequent unsubscription cancels it).

session receive notifications from topics that they are subscribed to via subscription streams (see below). When a session is subscribed to a topic, all matching streams will first receive a subscription notification that provides details about the topic. If the server has a value for the topic, the value will be delivered to the streams before any other notifications.

When a stream is added it will immediately be notified of any topics that are already subscribed to that would be selected for the stream. For certain topic types (TopicType.JSON, TopicType.BINARY, and TopicType.SINGLE_VALUE) the subscription notification will be followed by the latest known value. Other topic types do not support the local caching of values. To ensure that a value is received first, streams must be added before subscription.

A session can request unsubscription from a topic or topics at any time. This is also specified using topic selectors. On unsubscription, matching streams will be notified via the OnUnsubscription notification. This notification will give the reason for unsubscription (i.e.by request of session, request of the server, or topic removal).

Subscriptions and unsubscriptions can occur for reasons other than requests from the session. A session can be subscribed to or unsubscribed from a topic by another session using the subscription control feature, or by a publisher component hosted on the server. The removal of a topic also automatically causes unsubscription for subscribed sessions.

Subscription requests are subject to authorization checks. The session must have SELECT_TOPIC permission for the topic selector used to subscribe. Matching topics will be further filtered to those for which the session has READ_TOPIC permission.

Subscription streams

A session can listen to subscription events and updates for a selection of topics by adding one or more streams. A stream is registered using a selector which specifies the topics that the stream applies to. When an update is received for a topic then it will be routed to every stream that matches both the topic selector and the stream's data type. If more than one stream matches, all will receive the update; the order in which they are notified is not defined.

A stream can be added several times for different selectors. If the same stream (determined by object.Equals(object)) is registered for several selectors that match an event, the stream will be only notified of the event once. The mapping of topic selectors to streams is maintained locally in the client process.

A stream will receive an OnClose callback when unregistered and an OnError callback with a SESSION_CLOSED reason if the session is closed.

It is also possible to specify one or more fallback streams which will receive updates that have not been routed to any other stream. A fallback stream can be added to receive updates that have not been routed to any other stream. This is useful for default processing or simply to catch unprocesse updates. A fallback stream can be added using AddFallbackStream{TValue} or AddFallbackTopicStream. Zero, one, or more fallback streams can be assigned.If no fallback stream is specified, any updates that are not routed to any other stream will simply be discarded.

There are two types of subscription stream, value streams and topic streams as outlined below:

Value streams

A IValueStream will receive values for matching topics as and when updates are received from the server. Value streams are typed to a specified value type and only values for topics that maintain locally cached values matching the type will be routed to the stream. Delta updates from the server are automatically applied to locally cached values so that the stream always receives values.

This is the preferred stream type as it is the simplest to use; however, it is not supported for all topic types. The following table shows how the value class specified when adding the stream maps to actual topic types that will be routed to the stream:

Value Type	Topic Types
IJSON	JSON
IBinary	BINARY
IBytes	SINGLE_VALUE IJSON IBinary
IContent	SINGLE_VALUE IJSON IBinary

One or more such stream implementations can be added using IValueStream.

Topic streams

A topic stream will receive both value and delta updates for all topic types.

The server initially sends the current value of a topic when a session subscribes to the topic but after that, if it is more efficient to do so, the server will just send the changes (deltas). This type of stream provides the value and the deltas but relies upon the application to apply the deltas to a session-maintained current value. A topic stream is therefore not as convenient as a value stream but is currently the only option available for some topic types (such as RECORD).

One or more such stream implementations can be added using AddTopicStream(string,ITopicStream).

Fetch

A session can issue a request to fetch the state of a topic or topics (subject to authorization) at any time. Fetch requests use topic selectors to select the topics to fetch and because such a request could result in the fetching of many topics, a IStream type callback is used.

Fetch requests are subject to authorization checks. The session must have SELECT_TOPIC permission for the topic selector used to fetch. Matching topics will be further filtered to those for which the session has READ_TOPIC permission.

Access control

A session must have SELECT_TOPIC permission for the path prefix of the topic selector used to subscribe or fetch. The topics that result from a subscription or fetch request are further filtered using the READ_TOPIC permission.

The READ_TOPIC permission is required to retrieve the topic details.

No access control restrictions are applied to unsubscription.

Accessing the feature

This feature can be obtained from a session as follows:

var topics = session.GetTopicsFeature();

Since 5.0

Member Function Documentation

void PushTechnology.ClientInterface.Client.Features.ITopics.AddFallbackStream< TValue > ( IValueStream< TValue > stream )

Adds a fallback value stream.

See ITopics documentation for full details regarding the use of fallback streams.

Since 5.7

Template Parameters

TValue The value type.

Parameters

stream The stream to add.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The given stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddFallbackTopicStream ( ITopicStream stream )

Adds a fallback topic stream.

See ITopics documentation for full details regarding the use of fallback streams.

Since 5.1

Parameters

stream The topic stream to add as a fallback stream.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The given stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddStream< TValue >	(	ITopicSelector	topics,
		IValueStream< TValue >	stream
	)

Adds a value stream to receive topic events for topics that match a given PushTechnology.ClientInterface.Client.Topics.ITopicSelector and have a value type that matches the specified type.

See ITopics documentation for full details of the use of value streams.

Since 5.7

Template Parameters

TValue The value type.

Parameters

topics	The selector of one or more topics.
stream	The stream to add.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The topics or stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddStream< TValue >	(	string	topics,
		IValueStream< TValue >	stream
	)

Adds a value stream to receive topic events for topics that match a given PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression and have a value type that matches the specified type.

See ITopics documentation for full details of the use of value streams.

Since 5.7

Template Parameters

TValue The value type.

Parameters

topics	The topics as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression.
stream	The stream to add.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The topics or stream is null.
ArgumentException	Given topics is not a valid selector expression.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddTopicStream	(	ITopicSelector	topics,
		ITopicStream	stream
	)

Adds a topic stream to receive topic updates for topics that match the given PushTechnology.ClientInterface.Client.Topics.ITopicSelector.

Since 5.1

Parameters

topics	Selector of one or more topics.
stream	The topic stream to add.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The topics or stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddTopicStream	(	string	topics,
		ITopicStream	stream
	)

Adds a topic stream to receive topic events for all topics that match a given PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression.

This is equivalent to calling AddTopicStream(PushTechnology.ClientInterface.Client.Topics.ITopicSelector,PushTechnology.ClientInterface.Client.Features.ITopicStream) with a selector parsed from the given string expression.

Since 5.1

Parameters

topics	The topics as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression.
stream	The topic stream to add.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The topics or stream is null.
ArgumentException	The topics is not a valid selector expression.

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch	(	ITopicSelector	topics,
		IFetchStream	callback
	)

Fetches the current state of topics.

The stream callback's PushTechnology.ClientInterface.Client.Features.IFetchStream.OnFetchReply(string, PushTechnology.ClientInterface.Client.Content.IContent) method will be called for each topic that matches the given topics for which a fetch request can be satisfied, followed by PushTechnology.ClientInterface.Client.Features.IFetchStream.OnClose().

Since 5.0

Parameters

topics	The topics to fetch.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch	(	string	topics,
		IFetchStream	callback
	)

Fetches the current state of topics.

This is equivalent to calling Fetch(PushTechnology.ClientInterface.Client.Topics.ITopicSelector,PushTechnology.ClientInterface.Client.Features.IFetchStream) with a selector parsed from the given string expression.

Since 5.0

Parameters

topics	The PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression specifying the topics to fetch.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null or the the given topics cannot be parsed as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector.

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch< TContext >	(	ITopicSelector	topics,
		TContext	context,
		IFetchContextStream< TContext >	callback
	)

Fetches the current state of topics.

The stream callback's PushTechnology.ClientInterface.Client.Features.IFetchContextStream{TContext}.OnFetchReply(TContext, string, PushTechnology.ClientInterface.Client.Content.IContent) method will be called for each topic that matches the given topics for which a fetch request can be satisfied, followed by PushTechnology.ClientInterface.Client.Features.IFetchContextStream{TContext}.OnClose(TContext).

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The topics to fetch.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch< TContext >	(	string	topics,
		TContext	context,
		IFetchContextStream< TContext >	callback
	)

Fetches the current state of topics.

This is equivalent to calling Fetch{TContext}(PushTechnology.ClientInterface.Client.Topics.ITopicSelector,TContext,PushTechnology.ClientInterface.Client.Features.IFetchStream) with a selector parsed from the given string expression.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression specifying the topics to fetch.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null or the the given topics cannot be parsed as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector.

void PushTechnology.ClientInterface.Client.Features.ITopics.GetTopicDetails	(	string	topicPath,
		TopicDetailsLevel	level,
		ITopicDetailsCallback	callback
	)

Gets the details of a given topic.

The PushTechnology.ClientInterface.Client.Features.ITopicDetailsCallback.OnTopicDetails(string,PushTechnology.ClientInterface.Client.Topics.ITopicDetails) callback method will be called with the result.

Since 5.0

Parameters

topicPath	The full path of the topic.
level	The required level of detail.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics, level or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.GetTopicDetails< TContext >	(	string	topicPath,
		TopicDetailsLevel	level,
		TContext	context,
		ITopicDetailsContextCallback< TContext >	callback
	)

Gets the details of a given topic.

The PushTechnology.ClientInterface.Client.Features.ITopicDetailsContextCallback{TContext}.OnTopicDetails(TContext,string,PushTechnology.ClientInterface.Client.Topics.ITopicDetails) callback method will be called with the result.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topicPath	The full path of the topic.
level	The required level of detail.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics, level or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.RemoveStream ( Callbacks.IStream stream )

Removes a stream.

More formally, this method removes all streams that compare equal to the given stream, regardless of the topic selector for which they are registered. It will also remove any fallback stream equal to the given stream. If there are no such streams, no changes are made.

Since 5.7

Parameters

stream The value stream to remove.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The given stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.RemoveTopicStream ( ITopicStream stream )

Removes a topic stream.

Deprecated since 5.8. Use ITopics.RemoveStream() instead.

More formally, this method removes all topic streams that compare equal to the given stream, regardless of the topic selector for which they are registered. It will also remove any fallback stream equal to the given stream. If there are no such topic streams, no changes are made.

Since 5.1

Parameters

stream The topic stream to remove.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	The stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe	(	ITopicSelector	topics,
		ITopicsCompletionCallback	callback
	)

Requests subscription to topics.

Since 5.0

Parameters

topics	The topics to subscribe to.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe	(	string	topics,
		ITopicsCompletionCallback	callback
	)

Requests subscription to topics.

This is equivalent to calling Subscribe(PushTechnology.ClientInterface.Client.Topics.ITopicSelector,ITopicsCompletionCallback) with a selector parsed from the given string expression.

Since 5.0

Parameters

topics	The PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression specifying the topics to request subscription to.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null or the the given topics cannot be parsed as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe< TContext >	(	ITopicSelector	topics,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Requests subscription to topics.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The topics to subscribe to.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe< TContext >	(	string	topics,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Requests subscription to topics.

This is equivalent to calling Subscribe{TContext}(PushTechnology.ClientInterface.Client.Topics.ITopicSelector,TContext,PushTechnology.ClientInterface.Client.Features.ITopicsCompletionContextCallback{TContext}) with a selector parsed from the given string expression.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression specifying the topics to request subscription to.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null or the the given topics cannot be parsed as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector.

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe	(	ITopicSelector	topics,
		ITopicsCompletionCallback	callback
	)

Unsubscribes from topics.

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

Since 5.0

Parameters

topics	The topics to unsubscribe from.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe	(	string	topics,
		ITopicsCompletionCallback	callback
	)

Unsubscribes from topics.

This is equivalent to calling Unsubscribe(PushTechnology.ClientInterface.Client.Topics.ITopicSelector,PushTechnology.ClientInterface.Client.Features.ITopicsCompletionCallback) with a selector parsed from the given string expression.

Since 5.0

Parameters

topics	The PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression specifying the topics to unsubscribe from.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null or the the given topics cannot be parsed as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector.

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe< TContext >	(	ITopicSelector	topics,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Unsubscribes from topics.

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The topics to unsubscribe from.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe< TContext >	(	string	topics,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Unsubscribes from topics.

This is equivalent to calling Unsubscribe{TContext}(PushTechnology.ClientInterface.Client.Topics.ITopicSelector,TContext,PushTechnology.ClientInterface.Client.Features.ITopicsCompletionContextCallback{TContext}) with a selector parsed from the given string expression.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The PushTechnology.ClientInterface.Client.Topics.ITopicSelector expression specifying the topics to unsubscribe from.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

InvalidOperationException	The session is closed.
ArgumentNullException	Topics or callback is null or the the given topics cannot be parsed as a PushTechnology.ClientInterface.Client.Topics.ITopicSelector.

The documentation for this interface was generated from the following file:

UCIStack/Client/Features/ITopics.cs

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation