Requests

This section assumes a connection has been established; see the getting started tutorial as necessary.

The Session object provides different types of requests that all work in a similar way. Requests will generally take the following parameters:

• Request specific details (query or topic to subscribe/snapshot to).
• An optional callback handler to process the results of the request.
• An optional reference to parameters that change the behaviour of the request.

Handles

Each request will return a handle object that manages the lifetime of the request, and can be used to process the request.

Each handle has a delete() method that can be called to finish the request. This will mean no more results will be returned. Each handle also provides an Async Iterator that can be used to process the results of the request.

// With a connected session.

// Initiate a request
let topicIdHandle = session.query({
    dataSourceId: activOneApi.DataSourceId.activ,
    tagExpression: "type=listing and country=US and symbol=CAJ.*"
});

(async() => {
    // Use an async iterator to process the results
    for await (let topicIdResult of topicIdHandle) {
        // Use the result.
    }
})();

// At some point later call delete to close the request and stop any more results being processed.
topicIdHandle.delete();

Callback handlers

The easiest way to process the results of a request is often using a callback handler. They have different callbacks depending on the request, some provide feedback on the status of the request itself, while others provide the data. Callback functions don't have to return any value, but if they return true or a Promise that resolves to true the request will be closed and no more updates will be received.

// With a connected session.

// Initiate a request with a callback handler
session.query(
    {
        dataSourceId: activOneApi.DataSourceId.activ,
        tagExpression: "type=listing and country=US and symbol=CAJ.*",
    },
    {
        onQueryAdd(topicId) {
            // Handle the topic being added.

            // Not returning anything which so the query stays open.
        },
        onQueryRemove(topicId) {
            // Handle the topic being removed.

            // Returning true will finish the query and no more callbacks will be received.
            return true;
        },
    }
);

Head to Queries, Snapshots and Subscriptions for examples of the actual requests.