Just a second...

Fetching the current value of a topic

A client can send a fetch request for the values and/or topic specifications of a set of topics. The result set can be filtered by topic selector and topic path range.

Required permissions: select_topic and read_topic permissions for the specified topics

A fetch request enables you to retrieve values and/or topic specifications for a set of topics without subscribing to the topics.

In Diffusion™ 6.2, there is a new enhanced fetch API, and the old fetch API is deprecated. This documentation describes the new API.

Note: The old fetch API triggered missing topic notifications. The new enhanced API does not cause missing topic notifications.

Results can be filtered by topic selector and topic path range. A request can specify the maximum number of results to return, avoiding the inefficient transfer of very large result sets.

A request can specify the value type of topics to be returned, in which case only topics of types compatible with the given value type will be returned. Returned values will be typed accordingly, avoiding the need for data conversion.

Here is how to fetch the value of a topic or set of topics by using a topic selector to make a fetch request:

Java and Android
session = Diffusion.sessions().principal("client").password("password") .open(serverUrl);
                        
    topics = session.feature(Topics.class);
                        
    FetchResult<String> result =  
        topics.fetchRequest()
            .withValues(String.class)
            .fetch("*.*").get(5, SECONDS);

To get the result set and print the results:

Java and Android
List<TopicResult<Void>> results = result.results();
    results.forEach(t -> {
         System.out.println(t.type() + " : " + t.path());
    });

Fetching topic specifications

You can return topic specifications instead of values for each topic selected.

Java and Android
FetchResult<Void> result = 
    topics.fetchRequest()
        .withProperties()
        .fetch("*Accounts/").get(5, SECONDS);

TopicResult<Void> topicResult = result.get(0);
Map<String, String> properties = topicResult.specification().getProperties();
                    

Filtering by topic type

The results can also be restricted to topics of a particular topic type or types:
Java and Android
FetchResult<Void> result = 
    topics.fetchRequest()
        .topicTypes(EnumSet.of(TopicType.STRING, TopicType.INT64))
        .fetch("*Accounts/").get(5, SECONDS);
                    

Restricting the results to a range of topics

You can restrict the returned results to within a specified range of topics. All the topics within the selection that have a path that is lexically within the specified range will be returned, at all levels.

You can specify either a start point or an end point or both. For example, if you specify a start point but no end point, results will be returned from the start point up to the end of the topic tree.

The specified start and end points do not need to represent topics that actually exist.

Java and Android
FetchResult<Bytes> result = 
    topics.fetchRequest()
        .withValues(Bytes.class)    
        .from("Accounts/Dept05")
        .to{"Accounts/Dept10")
        .fetch("*Accounts/").get(5, SECONDS);
This example will return all topics under Accounts from Accounts/Dept05 to Accounts/Dept10 inclusive.

Paging through topics

You can specify a non-inclusive range using the after and before methods. You can limit the number of results and check if there are further results remaining.

By combining these, you can page through a topic tree. This can be useful when there is a large number of topics and you wish to access it in manageable chunks, for example when presenting results from a large set into a limited window in a user interface.

Here is an example of paging through all string topics in a topic tree, in chunks of 20:

Java and Android
FetchRequest request = 
    topics.fetchRequest()
        .withValues(String.class)
        .first(20);
    FetchResult<String> result = request.fetch("*.*").get(5, SECONDS);
    if (result.hasMore()) {
        result = request.after(result.results.get(19).path()).fetch("*.*");
    }