TickCursor Interface Overview

Reading Messages

TickCursor API allows reading TimeBase stream messages.

Cursors consume messages one by one in exactly the same chronological order as they have been written by Loaders. 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. Make sure to use getMessage() data prior the following cursor.next() operation or copy the returned message using copyFrom() method of an InstrumentMessage function. Call cursor.close() once reading is completed.

// 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));
    }  
}

Reverse Reading

As we have already mentioned, Cursors read messages in a chronological order. Nevertheless, you can read messages in the reversed order by using reverse cursors.

options.reversed = 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.

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

Real-Time Notifications

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

options.realTimeNotification = false;

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 allows cursors receiving such messages even if they are out of order with respect to the current reading time.

options.allowLateOutOfOrder = false;

Reading Raw Messages

Cursors can read raw messages or bound to native classes.

//read data in raw mode
options.raw = true;

Subscriptions

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

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

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

Reading from Unique Streams

Get a cached unique stream snapshot by adding the following options:

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