com.pushtechnology.diffusion.client.features

Interface Topics.FetchRequest<V>

Type Parameters:

V - The value type of the request.

Enclosing interface:

Topics

public static interface Topics.FetchRequest<V>

A parameterised query that can be used to search the topic tree.

A new request can be created using the fetchRequest method and modified to specify a range of topics and/or various levels of detail. The request can then be issued to the server using the fetch method supplying a topic selector which specifies the selection of topics. The results are returned via a CompletableFuture.

As a minimum, the path and type of each selected topic 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 provided valueClass argument. So if String.class is specified, only STRING topics will be selected. However, if JSON.class is specified, all types compatible with JSON will be selected including STRING, INT64 and DOUBLE. See DataType.canReadAs(Class) for the class hierarchy of types. Selecting a value class of Object.class will return values for all topic types.

If values are requested, the request and results are typed to the value type, otherwise the type is Void. 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.

The values of time series topics are only returned if the specified value class is Object. In this case the value returned represents the latest event appended to the topic and is of type Event<Bytes> The bytes value from the event can then be read using the DataType corresponding to the time series event value type of the topic. A time series range query can be used to retrieve all the events of a time series topic.

The topics selected by the topic selector can be further restricted by range. A range is defined by a start path and an end path, and contains all paths in-between in path order. Given a topic tree containing the topics:

 a, a/b, a/c, a/c/x, a/c/y, a/d, a/e, b, b/a/x, b/b/x, c
 

The range from a/c/y to b/a/x includes the topics with paths:

 a/c/x, a/c/y, a/d, a/e, b, b/a/x
 

The start point of a range can be specified using from or after and an end point using to or before. from and to include any topic with the specified path in the selection, whereas after and before 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 first topic of the topic tree, ordered by path name. Similarly, if no end point is specified, the end point is the last topic of the topic tree.

A limit on the number of results returned can be specified using first. This is advisable if the result set could potentially be large. The number of results returned is also limited by the session's maximum message size – see maximumResultSize(int). The result indicates whether the results have been limited via the hasMore method. If hasMore returns true, further results can be retrieved by modifying the original query to request results after(java.lang.String) the last path received.

By default, 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. This method complements first(int), returning up to the specified number of results from the end of the range, but in reverse path order. This is useful for paging backwards through a range of topics.

It can be useful to explore an unknown topic tree in a breadth-first manner rather than the path order. This can be achieved using limitDeepBranches(int, int).

FetchRequest instances are immutable and can be safely shared and reused.

Since:

6.2

Field Summary

Fields

Modifier and Type	Field and Description
static Set<TopicType>	ALL_TYPES A constant set of all topic types that can be fetched.

Method Summary

Modifier and Type	Method and Description
Topics.FetchRequest<V>	after(String topicPath) Specifies a logical start point within the topic tree.
Topics.FetchRequest<V>	before(String topicPath) Specifies a logical end point within the topic tree.
CompletableFuture<Topics.FetchResult<V>>	fetch(String topics) Sends a fetch request to the server.
CompletableFuture<Topics.FetchResult<V>>	fetch(TopicSelector topics) Sends a fetch request to the server.
Topics.FetchRequest<V>	first(int number) Specifies a maximum number of topic results to be returned from the start of the required range.
Topics.FetchRequest<V>	from(String topicPath) Specifies a logical start point within the topic tree.
Topics.FetchRequest<V>	last(int number) Specifies a maximum number of topic results to be returned from the end of the required range.
Topics.FetchRequest<V>	limitDeepBranches(int deepBranchDepth, int deepBranchLimit) Specifies a limit on the number of results returned for each deep branch.
Topics.FetchRequest<V>	maximumResultSize(int maximumSize) Specifies the maximum data size of the result set.
Topics.FetchRequest<V>	to(String topicPath) Specifies a logical end point within the topic tree.
Topics.FetchRequest<V>	topicTypes(Set<TopicType> topicTypes) Specifies that only topics of the specified topic types should be returned.
Topics.FetchRequest<V>	withProperties() Specifies that all properties associated with each topic's specification should be returned.
Topics.FetchRequest<V>	withSizes() Specifies that topic sizes should be returned.
Topics.FetchRequest<V>	withUnpublishedDelayedTopics() Include the details of reference topics that are not yet published.
<T> Topics.FetchRequest<T>	withValues(Class<? extends T> valueClass) Specifies that values should be returned for selected topics, constraining the selection to only those topics with a data type compatible with the specified value class.

Field Detail

ALL_TYPES

static final Set<TopicType> ALL_TYPES

A constant set of all topic types that can be fetched.

Method Detail

from

Topics.FetchRequest<V> from(String topicPath)

Specifies a logical start point within the topic tree.

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 and if used will override any previous after or from constraint.

Parameters:

topicPath - the topic path from which results are to be returned

Returns:

a new fetch request derived from this fetch request but selecting only topics from the specified path onwards (inclusive)

after

Topics.FetchRequest<V> after(String topicPath)

Specifies a logical start point within the topic tree.

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 and if used will override any previous from or after constraint.

Parameters:

topicPath - the topic path after which results are to be returned

Returns:

a new fetch request derived from this fetch request but selecting only topics after the specified path (not inclusive)

to

Topics.FetchRequest<V> to(String topicPath)

Specifies a logical end point within the topic tree.

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 and if used will override any previous before or to constraint.

Parameters:

topicPath - the topic path to which results are to be returned

Returns:

a new fetch request derived from this fetch request but selecting only topics including and before the specified path (inclusive)

before

Topics.FetchRequest<V> before(String topicPath)

Specifies a logical end point within the topic tree.

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 and if used will override any previous to or before constraint.

Parameters:

topicPath - the topic path before which results are to be returned

Returns:

a new fetch request derived from this fetch request but selecting only topics before the specified path (not inclusive)

topicTypes

Topics.FetchRequest<V> topicTypes(Set<TopicType> topicTypes)

Specifies that only topics of the specified topic types should be returned.

If this is not specified, all types will be returned (unless constrained by withValues).

If the specified topic type matches the event type of a time series topic it will also be returned. The value will be delivered without the associated metadata. To specify all time series topics use TopicType.TIME_SERIES

This may be used instead to further constrain the results when using withValues. For example, you can specify JSON.class to withValues 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 has been specified then the types specified here must be compatible with the value class specified or the event type for time series topics.

Parameters:

topicTypes - topic types to be selected

Returns:

a new fetch request derived from this fetch request but specifying that only topics of the specified topic types should be returned

withValues

<T> Topics.FetchRequest<T> withValues(Class<? extends T> valueClass)

Specifies that values should be returned for selected topics, constraining the selection to only those topics with a data type compatible with the specified value class.

If Object.class is specified, values will be returned for all topic types (unless constrained by topicTypes).

The specified value constrains the topic types. So, any topic types specified in a previous call to topicTypes that cannot be read as the specified class will be removed from the list of topic types.

Parameters:

valueClass - the class of values. If null is specified this will cancel any previous call (topic types will remain unchanged).

Returns:

a new fetch request derived from this fetch request but specifying that only topics compatible with the specified class should be returned with values

Throws:

IllegalArgumentException - if the class is not compatible with any topic types.

withSizes

Topics.FetchRequest<V> withSizes()

Specifies that topic sizes should be returned.

For time series topics this will fetch the size (in bytes) of the last event, the number of events, and the total size of all events.

For all other topics this will fetch the size (in bytes) of the topic value, or 0 if the topic has no value.

Returns:

a new fetch request derived from this fetch request but specifying that topic sizes should be returned.

Since:

6.11

withProperties

Topics.FetchRequest<V> withProperties()

Specifies that all properties associated with each topic's specification should be returned.

Returns:

a new fetch request derived from this fetch request but specifying that topic specification properties should be returned

withUnpublishedDelayedTopics

Topics.FetchRequest<V> withUnpublishedDelayedTopics()

Include the details of reference topics that are not yet published.

Topic views 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.

Returns:

a new fetch request derived from this fetch request, additionally specifying that unpublished reference topics should be included in the results

Since:

6.5

first

Topics.FetchRequest<V> first(int number)

Specifies a maximum number of topic results to be returned from the start of the required range.

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 method.

Zero can be supplied to return no results. Such a request can be used together with Topics.FetchResult.hasMore() to query whether there are topics that match the selector provided to fetch(com.pushtechnology.diffusion.client.topics.TopicSelector), without retrieving the details of any of the topics. To retrieve unlimited topics use Integer.MAX_VALUE which is the default value.

Either this or last may be specified. This will therefore override any previous last or first constraint.

Parameters:

number - the maximum number of results to return from the start of the range

Returns:

a new fetch request derived from this fetch request but selecting only the number of topics specified from the start of the range

last

Topics.FetchRequest<V> last(int number)

Specifies a maximum number of topic results to be returned from the end of the required range.

This is similar to first 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. Results are always returned in topic path order (not reverse order).

Zero can be supplied to return no results. Such a request can be used together with Topics.FetchResult.hasMore() to query whether there are topics that match the selector provided to fetch(com.pushtechnology.diffusion.client.topics.TopicSelector), without retrieving the details of any of the topics. To retrieve unlimited topics use Integer.MAX_VALUE which is the default value.

Either this or first may be specified. This will therefore override any previous first or last constraint.

Parameters:

number - the maximum number of results to return from the end of the range

Returns:

a new fetch request derived from this fetch request but selecting only the number of topics specified from the end of the range

maximumResultSize

Topics.FetchRequest<V> maximumResultSize(int maximumSize)

Specifies the maximum data size of the result set.

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 SessionFactory.maximumMessageSize(int) is used.

Parameters:

maximumSize - the maximum size of the result set in bytes. If a value greater than the session's maximum message size is specified, the maximum message size will be used.

Returns:

a new fetch request derived from this fetch request but constraining the size of the result to the specified maximum

limitDeepBranches

Topics.FetchRequest<V> limitDeepBranches(int deepBranchDepth,
                                         int deepBranchLimit)

Specifies a limit on the number of results returned for each deep branch.

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
 

Then

 FetchResult result =
     topics.fetchRequest().limitDeepBranches(1, 1).fetch("?.//").get();
 

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,

 FetchResult result =
     topics.fetchRequest().limitDeepBranches(3, 0).fetch("?.//").get();
 

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.

Parameters:

deepBranchDepth - the number of parts in the root path of a branch for it to be considered deep

deepBranchLimit - the maximum number of results to return for each deep branch

Returns:

a new fetch request derived from this fetch request but restricting the number of results for deep branches

Since:

6.4

fetch

CompletableFuture<Topics.FetchResult<V>> fetch(TopicSelector topics)

Sends a fetch request to the server.

Results are returned for all topics matching the selector that satisfy the request constraints within any range defined by from/after and/or to/before.

Parameters:

topics - specifies a topic selector which selects the topics to be fetched

Returns:

a CompletableFuture that completes when a response is received from the server with the results of the fetch operation.

If the task completes successfully, the CompletableFuture result will be an object encapsulating all of the results.

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• PermissionsException – if the calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression;
• SessionClosedException – if the session is closed.

fetch

CompletableFuture<Topics.FetchResult<V>> fetch(String topics)

Sends a fetch request to the server.

This is the equivalent of fetch(TopicSelector), with the convenience of directly specifying the selector as a String.

Parameters:

topics - specifies a topic selector string which selects the topics to be fetched

Returns:

a CompletableFuture that completes when a response is received from the server with the results of the fetch operation.

If the task completes successfully, the CompletableFuture result will be an object encapsulating all of the results.

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• PermissionsException – if the calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression;
• SessionClosedException – if the session is closed.