TickCursor API

Reading Messages

TickCursor API allows reading messages from streams.

Cursors consume messages one by one in exactly the same chronological order as they have been written by Loaders.

note

You can create cursors on the TickDb and a TickStream level using select() or executeQuery().

• Pass data selection options as SelectionOptions().
• Use cursor.next() operation to increment the current cursor position to the next message.
• getMessage() is used with every cursor.next() and returns the message the cursor is pointing to.
• Call cursor.close() once reading is completed.

Java

Create a new cursor to read all types of messages from the beginning of the stream.

SelectionOptions options = new SelectionOptions();
try (TickCursor cursor = stream.select(Long.MIN_VALUE, options)) 
{
    // Iterate cursor and get messages
    while (cursor.next()) {
        InstrumentMessage message = cursor.getMessage();
        System.out.println("Read message: " + message.toString());
        messages.add(new InstrumentMessage().copyFrom(message));
    }  
}

Python

with stream.trySelect(tbapi.JAVA_LONG_MIN_VALUE, tbapi.SelectionOptions(), None, None) as cursor:
    # iterate cursor
    while cursor.next():
        message = cursor.getMessage()
        print(message)

tip

Make sure to use getMessage() data prior the following cursor.next() operation or copy the returned message using copyFrom() method of an InstrumentMessage() function.

info

Refer to code samples to view more reading examples.

Reverse Reading

As we have already mentioned, Cursors read messages in a chronological order. Nevertheless, you can read messages in the reversed order by adding reversed selection option.

Java

Add selection option Reversed

options.reversed = true;

Python

options = tbapi.SelectionOptions()
options.reverse = True

Live Reading

cursor.next() operation returns false as soon as you have reached the end of the stream and/or there are no more messages to read. Hence, you can make cursor.next() wait for new messages to come. Cursors that do that are called live cursors. Add live selection option when creating a cursor to activate a live cursor.

Java

Add selection option Live

options.live = true;
// do select ...
while (cursor.next()) { // next() will wait for new messages
    ...
}

Python

options = tbapi.SelectionOptions()
options.live = True;

with stream.trySelect(tbapi.JAVA_LONG_MIN_VALUE, options, None, None) as cursor:
    # iterate cursor
    while cursor.next():
        message = cursor.getMessage()

Real-Time Notifications

Use realTimeNotification flag in selection options to enable/disable notifications when you transition from reading historical data to live-reading mode.

When live cursor is used to read stream from some time in the past (bootstrap with historical data) there is an option to get notified when live cursor is done reading historical data and switched to live data. With this option cursor will give you special RealtimeStartedMessage that marks end of historical data. 

To enable this feature set SelectionOption.realTimeNotification flag (default is false)

Java

Add selection option realTimeNotification

options.realTimeNotification = false;

Python

options = tbapi.SelectionOptions()
options.realTimeNotification = True

Reading Out-of-Order Late Messages

TimeBase cursors receive historical messages in a strictly chronological order. In live-mode reading scenarios, it is possible that newly-arrived messages have timestamps in the time range that has already been read. allowLateOutOfOrder flag in selection options allows receiving such messages even if they are out of order with respect to the current reading time.

Java

Add selection option allowLateOutOfOrder

options.allowLateOutOfOrder = false;

Python

options = tbapi.SelectionOptions()
options.allowLateOutOfOrder = True

caution

Messages with timestamps prior to cursor's select time or last reset time will not be delivered even with allowLateOutOfOrder enabled.

Reading Raw Messages

Cursors can read raw messages or bound to native classes. Use raw selection option to read unbound messages.

Add selection option Raw

options.raw = true;

info

Refer to Data Encoding for more information about encoding and decoding messages.

Subscriptions

Cursors can read messages based on a specific subscription. Basic subscription can be created using select() when creating a cursor.

Java

try (TickCursor cursor = stream.select(Long.MIN_VALUE, new SelectionOptions(), types, identities)) { 
    // read data 
} 

Python

with stream.trySelect(tbapi.JAVA_LONG_MIN_VALUE, tbapi.SelectionOptions(), types, identities) as cursor:
    # iterate cursor
    while cursor.next():
        message = cursor.getMessage()

info

Subscriptions can be modified on the fly - refer to Dynamic Subscription Change for more information.

Reading from Unique Streams

You can get a cached unique stream snapshot by adding the following options:

• options.rebroadcast - use to rebroadcast unique message on open/reset cursors.
• options.allowLateOutOfOrder - refer to the late messages section.

options.rebroadcast = true;  
options.allowLateOutOfOrder = true;

info

Refer to Stream to learn more about unique streams.

Reading from Spaces

In selection options you can set a specific space to read from. If set then data only from the specified space will be loaded. If set to {@code null} then data from all spaces is loaded. Any non-null value is permitted only for streams that supports spaces.

Populate selection option to read from a Space

options.space = "mySpace";

info

• Refer to Data Distribution for more information about working with spaces.
• Refer to TickLoader API for more information about writing into spaces.
• Refer to How To to learn more about spaces and how to work with them.