new FetchRequest()
A fetch request.
This defines a fetch request to be made to the server. 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 fetch request is issued to the server using the fetch 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 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 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 {diffusion.datatypes.DataType.string} is specified, only STRING topics will be selected. However, if {diffusion.datatypes.DataType.json} is specified, all types compatible with JSON will be selected including STRING, INT64 and DOUBLE. See diffusion.datatypes.DataType#canReadAs for the class hierarchy of 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. 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 method.
The request can be sent to the server using fetch and the results are returned (via a Result.<FetchResult>) 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 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.
Slave topics are supported, in that if the slave topic itself is within the requested selector/range and it is currently linked to a topic that should be selected then a result will be returned for the slave topic with the type/value/properties of the source topic.
Routing topics are not supported, and if encountered will be ignored (i.e. treated as if they did not exist).
FetchRequest instances are immutable and can be safely shared and reused.
- Since:
-
- 6.2
Methods
-
<static> getAllTypes()
-
Return a set of all topic types that can be fetched.
Returns:
the topic types that can be fetched by a FetchRequest
- Type
- Array.<diffusion.topics.TopicType>
-
after(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:
Name Type Description topicPathString 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)
- Type
- FetchRequest
-
before(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:
Name Type Description topicPathString 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)
- Type
- FetchRequest
-
fetch(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.
This function can take any number of arguments. Each argument can be a string or a TopicSelector. Alternatively, an array of strings and TopicSelectors can be passed as a single argument.
Parameters:
Name Type Description topicsString | TopicSelector | Array.<String> specifies a topic selector which selects the topics to be fetched
Returns:
a Result that resolves with a FetchResult when a response is received from the server with the results of the fetch operation.
If the task completes successfully, the FetchResult returned by the Result will be an object encapsulating all of the results.
Otherwise, the Result will resolve with an Error.
- Type
- Result.<FetchResult>
-
first(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.
Either this or last may be specified. This will therefore override any previous last or first constraint.
Parameters:
Name Type Description numberNumber 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
- Type
- FetchRequest
-
from(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:
Name Type Description topicPathString 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)
-
last(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).
Either this or first may be specified. This will therefore override any previous first or last constraint.
Parameters:
Name Type Description numberNumber 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
- Type
- FetchRequest
-
maximumResultSize(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 Session.Options.maxMessageSize is used.
Parameters:
Name Type Description maximumSizeNumber 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 butconstraining the size of the result to the specified maximum
- Type
- FetchRequest
-
to(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:
Name Type Description topicPathString 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)
- Type
- FetchRequest
-
topicTypes(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).
This may be used instead to further constrain the results when using withValues. For example, you can specify {diffusion.datatypes.DataType.json} 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.
Neither SLAVE nor ROUTING may be specified as only target topic types may be selected.
Parameters:
Name Type Description topicTypesArray.<diffusion.topics.TopicType> topic types to be selected
Throws:
-
if invalid topic types are specified
- Type
- Error
Returns:
a new fetch request derived from this fetch request but specifying that only topics of the specified topic types should be returned.
- Type
- FetchRequest
-
-
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.
- Type
- FetchRequest
-
withValues(dataType)
-
Specifies that values should be returned for selected topics, constraining the selection to only those topics with a data type compatible with the specified DataType.
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:
Name Type Description dataTypediffusion.datatypes.DataType the type of values. If no value is specified this will cancel any previous call (topic types will remain unchanged).
Throws:
-
if the class is not compatible with any topic types.
- Type
- Error
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.
- Type
- FetchRequest
-