Interface IFetchRequest
The fetch request.
Namespace: PushTechnology.ClientInterface.Client.Features
Assembly: Diffusion.Client.dll
Syntax
public interface IFetchRequest
Remarks
This defines a fetch request to be made to the server. A new request can be created using the FetchRequest property and modified to specify a range of topics and/or various levels of detail.
The fetch request is issued to the server using the FetchAsync(String) method supplying a topic selector which specifies the selection of topics.
A range is defined as being between two points of the topic tree which is ordered in full path name order. So an example tree order would be:
- a
- a/b
- a/c
- a/c/x
- a/c/y
- a/d
- a/e
- b
- b/a/x
- b/b/x
- c
The start point of a range can be specified using From(String) or After(String) and an end point using To(String) or Before(String). From(String) and To(String) include any topic with the specified path in the selection, whereas After(String) and Before(String) are non-inclusive and useful for paging through a potentially large range of topics. If no start point is specified, the start point is assumed to be the logical beginning of the topic tree. Similarly, if no end point is specified, the end point is the logical end of the topic tree. Ranges should be within the scope indicated by the topic selector used when issuing the fetch.
As a minimum, the path and type of each topic selected will be returned. It is also possible to request that the topic values and/or properties are returned.
If values are selected then the topic types selected are naturally constrained by the value class indicated. So
if string
is specified, only STRING topics will be selected. However, if
IJSON is specified, all types compatible with IJSON will be
selected including STRING, INT64 and
DOUBLE. See object
will return values for all topic types.
To select topic types when values are not required, or to further constrain the selection when values are required, it is also possible to specify exactly which topic types to select.
A limit on the number of results returned can be specified using First(Int32). This is advisable when the result set could potentially be large. When such a limit is used then the result will indicate whether more results for the same selection would be available via the HasMore property.
The request can be sent to the server using FetchAsync(String) and the results are returned in path order, earliest path first, starting from the beginning of any range specified.
It is also possible to request results from the end of the range indicated by specifying a limit to the number of results using Last(Int32). This returns up to the specified number of results from the end of the range, in path order. This is useful for paging backwards through a range of topics.
If values are requested, the request and results are typed to the value type (IFetchRequest<TValue> and IFetchResult<TValue> respectively), otherwise the non-generic versions of IFetchRequest and IFetchResult are being used.
IFetchRequest instances are immutable and can be safely shared and reused.
Methods
After(String)
Specifies a logical start point within the topic tree.
Declaration
IFetchRequest After(string topicPath)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path after which results are to be returned. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but selecting only topics after the specified path (not inclusive). |
Remarks
If specified, only results for topics with a path that is lexically 'after' the specified path will be returned.
This is the non-inclusive equivalent of From(String) and if used will override any previous From(String) or After(String) constraint.
Before(String)
Specifies a logical end point within the topic tree.
Declaration
IFetchRequest Before(string topicPath)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path before which results are to be returned. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but selecting only topics before the specified path (not inclusive). |
Remarks
If specified, only results for topics with a path that is lexically 'before' the specified path will be returned.
This is the non-inclusive equivalent of To(String) and if used will override any previous To(String) or Before(String) constraint.
FetchAsync(String)
Sends a fetch request to the server.
Declaration
Task<IFetchResult> FetchAsync(string topics)
Parameters
Type | Name | Description |
---|---|---|
String | topics | The topic selector string which selects the topics to be fetched. |
Returns
Type | Description |
---|---|
Task<IFetchResult> | The |
Remarks
If the operation completes successfully, the Task
result will be a
IFetchResult instance.
Results are returned for all topics matching the selector that satisfy the request constraints within any range defined by From(String)/After(String) and/or To(String)/ Before(String).
This method is the same as calling FetchAsync(String, CancellationToken) with
System.Threading.CancellationToken.None
.
Exceptions
Type | Condition |
---|---|
SessionSecurityException | The calling session does not have SELECT_TOPIC permission for the path
prefix of the selector expression. Thrown by the returned |
SessionClosedException | The calling session is closed. Thrown by the returned |
FetchAsync(String, CancellationToken)
Sends a fetch request to the server.
Declaration
Task<IFetchResult> FetchAsync(string topics, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | topics | The topic selector string which selects the topics to be fetched. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<IFetchResult> | The |
Remarks
If the operation completes successfully, the Task
result will be a
IFetchResult instance.
Results are returned for all topics matching the selector that satisfy the request constraints within any range defined by From(String)/After(String) and/or To(String)/ Before(String).
Exceptions
Type | Condition |
---|---|
SessionSecurityException | The calling session does not have SELECT_TOPIC permission for the path
prefix of the selector expression. Thrown by the returned |
SessionClosedException | The calling session is closed. Thrown by the returned |
First(Int32)
Specifies a maximum number of topic results to be returned from the start of the required range.
Declaration
IFetchRequest First(int number)
Parameters
Type | Name | Description |
---|---|---|
Int32 | number | The maximum number of results to return from the start of the range. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but selecting only the number of topics specified from the start of the range. |
Remarks
If this is not specified, the number of results returned will only be limited by other constraints of the request.
This should be used to retrieve results in manageable batches and prevent very large result sets.
If there are potentially more results that would satisfy the other constraints, then the fetch result will indicate so via the HasMore property.
Zero can be supplied to return no results. Such a request can be used together with HasMore to query whether there are topics that match the selector provided to FetchAsync(String), without retrieving the details of any of the topics. To retrieve unlimited topics use Int32.MaxValue which is the default value.
Either this or Last(Int32) may be specified. This will therefore override any previous Last(Int32) or First(Int32) constraint.
From(String)
Specifies a logical start point within the topic tree.
Declaration
IFetchRequest From(string topicPath)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path from which results are to be returned. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but selecting only topics from the specified path onwards (inclusive). |
Remarks
If specified, only results for topics with a path that is lexically equal to or 'after' the specified path will be returned.
This is the inclusive equivalent of After(String) and if used will override any previous After(String) or From(String) constraint.
Last(Int32)
Specifies a maximum number of topic results to be returned from the end of the required range.
Declaration
IFetchRequest Last(int number)
Parameters
Type | Name | Description |
---|---|---|
Int32 | number | The maximum number of results to return from the end of the range. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but selecting only the number of topics specified from the end of the range. |
Remarks
This is similar to First(Int32) except that the specified number of results are returned from the end of the range. This is useful for paging backwards through a range of topics. The results will be returned in topic path order (not reverse order).
Zero can be supplied to return no results. Such a request can be used together with HasMore to query whether there are topics that match the selector provided to FetchAsync(String), without retrieving the details of any of the topics. To retrieve unlimited topics use Int32.MaxValue which is the default value.
Either this or First(Int32) may be specified. This will therefore override any previous First(Int32) or Last(Int32) constraint.
LimitDeepBranches(Int32, Int32)
Specifies a limit on the number of results returned for each deep branch.
Declaration
IFetchRequest LimitDeepBranches(int deepBranchDepth, int deepBranchLimit)
Parameters
Type | Name | Description |
---|---|---|
Int32 | deepBranchDepth | The number of parts in the root path of a branch for it to be considered deep. |
Int32 | deepBranchLimit | The maximum number of results to return for each deep branch. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but restricting the number of results for deep branches. |
Remarks
A deep branch has a root path that has a number of parts equal to the deepBranchDepth
parameter. The deepBranchLimit
specifies the maximum number of results for each deep
branch.
This method is particularly useful for incrementally exploring a topic tree from the root, allowing a breadth-first search strategy.
For example, given a topic tree containing the topics with the following paths:
x/0
x/x/1
x/x/x/2
y/y/y/y/3
y/y/y/4
z/5
z/z/6
var result = await session.Topics.FetchRequest.LimitDeepBranches( 1, 1 ).FetchAsync( "?.//" );
will return results with the paths x/0
, y/y/y/y/3
, and z/5
. The application can then
determine the roots of the tree are x
, y
, and z
.
The deepBranchLimit
parameter can usefully be set to 0
. For example, given the
same example topic tree,
var result = await session.Topics.FetchRequest.LimitDeepBranches( 3, 0 ).FetchAsync( "?.//" );
will only return results having paths with fewer than three parts; namely x/0
, and z/5
.
The fetch result does not indicate whether this option caused some results to be filtered from deep
branches. It has no affect on the HasMore result. If the result set contains
deepBranchLimit
results for a particular deep branch, some topics from that branch may
have been filtered.
MaximumResultSize(Int32)
Specifies the maximum data size of the result set.
Declaration
IFetchRequest MaximumResultSize(int maximum)
Parameters
Type | Name | Description |
---|---|---|
Int32 | maximum | The maximum size of the result set in bytes. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but constraining the size of the result to the
specified |
Remarks
This may be used to constrain the size of the result. If not specified then by default the maximum message size for the session (as specified by MaximumMessageSize(Int32) is used.
If a value greater than the session's maximum message size then the maximum message size will be used.
To(String)
Specifies a logical end point within the topic tree.
Declaration
IFetchRequest To(string topicPath)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path before which results are to be returned. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but selecting only topics including and before the specified path. |
Remarks
If specified, only results for topics with a path that is lexically equal to or 'before' the specified path will be returned.
This is the inclusive equivalent of Before(String) and if used will override any previous Before(String) or To(String) constraint.
TopicTypes(IEnumerable<TopicType>)
Specifies that only topics of the specified topic types should be returned.
Declaration
IFetchRequest TopicTypes(IEnumerable<TopicType> topicTypes)
Parameters
Type | Name | Description |
---|---|---|
IEnumerable<TopicType> | topicTypes | The topic types to be selected. |
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but specifying that only topics of the specified topic types should be returned. |
Remarks
If this is not specified, all types will be returned (unless constrained by WithValues<TValue>()).
This may be used instead to further constrain the results when using WithValues<TValue>(). For example, you can specify IJSON to WithValues<TValue>() then specify JSON here to ensure that only JSON topics are returned and not those topics that are logically value subtypes of JSON (e.g. STRING).
If WithValues<TValue>() has been specified then the types specified here must be compatible with the specified value type.
WithProperties()
Specifies that all properties associated with each topic's ITopicSpecification should be returned.
Declaration
IFetchRequest WithProperties()
Returns
Type | Description |
---|---|
IFetchRequest | The new fetch request derived from this fetch request but specifying that topic specification properties should be returned. |
WithUnpublishedDelayedTopics()
Include the details of reference topics that are not yet published.
Declaration
IFetchRequest WithUnpublishedDelayedTopics()
Returns
Type | Description |
---|---|
IFetchRequest | A new fetch request derived from this fetch request, additionally specifying that unpublished reference topics should be included in the results |
Remarks
ITopicViews that use the delay by clause create reference topics in an unpublished state. The topics are published once the delay time has expired. A topic in the unpublished state prevents a lower priority topic view from creating a reference topic with the same path.
A reference topic in the unpublished state which matches the query will only be included in the fetch results if the session has READ_TOPIC permission for the reference's source topic as well as READ_TOPIC permission for the reference topic. Requiring READ_TOPIC permission for the source topic ensures less privileged sessions cannot derive information from the existence of the reference topic before the delay time has expired.
Added in version 6.5.
WithValues<TValue>()
Specifies that values should be returned for selected topics.
Declaration
IFetchRequest<TValue> WithValues<TValue>()
Returns
Type | Description |
---|---|
IFetchRequest<TValue> | The new fetch request derived from this fetch request but specifying that only topics compatible with the specified type should be returned with values. |
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
This constraints the selection to only those topics with a data type compatible with the specified
TValue
.
If object
is specified, values will be returned for all topic types (unless constrained by
TopicTypes(IEnumerable<TopicType>)).
The specified value constraints the topic types. So, any topic types specified in a previous call to TopicTypes(IEnumerable<TopicType>) that cannot be read as the specified class will be removed from the list of topic types.