TickStream Interface Overview

TickStream API allows getting information about streams, managing stream data, creating Cursors to read from and Loaders to write data into streams.

Stream Management

With TickStream you can get information about streams such as name, description, schema, scope and more.

Access specific stream data such as key, name, description, and other:

// get specific stream data 
String key = stream.getKey();

//Access a list of StreamOptions (list of stream parameters): 
StreamOptions options = stream.getStreamOptions();
String name = options.name;
String description = options.description;
StreamScope scope = options.scope;
RecordClassSet metadata = options.getMetadata();
// get specific stream data 
ITickStream stream = db.GetStream(key);

StreamOptions streamOptions = stream.GetStreamOptions();
String name = streamOptions.Name;
String description = streamOptions.Description;
StreamScope scope = streamOptions.Scope;

// stream schema
RecordClassSet classSet = streamOptions.GetMetaData();


TickStream allows you to change stream information. Stream Key and name are unique.

stream.setName("NewStreamName");
stream.setDescription("My awesome stream");
stream.setPolymorphic(descriptors);
stream.Name = "NewStreamName";
stream.Description = "My awesome stream";
RecordClassDescriptor[] descriptors;
...
stream.SetPolymorphicDescriptors(descriptors);

Entities

Each message has a “key” field called Symbol. Symbol represents domain-specific names such as IoT sensor name, trade instrument id, user id, etc. TimeBase streams use Symbols as permanent indices and allow filtering by Symbols. On an API level, each message implements IdentityKey interface holding Symbol string representation:

public interface IdentityKey {
    public CharSequence         getSymbol ();
}

Get a list of Symbols (keys) from TimeBase streams:

 IdentityKey[] ids = stream.listEntities();
IIdentityKey[] ids = stream.ListEntities();


To collect information about stream data TickStream has following methods:

  • getTimeRange() to get a time range for the entire stream or specific symbols.
  • listEntities() to get list of all symbols present in the stream.
// return timsetamps of the first and last message in the stream
long[] timerange = stream.getTimeRange(); 

// return timsetamps of the first and last message for the "EPAM" symbol
long[] symbolRange = stream.getTimeRange(new ConstantIdentityKey("EPAM")); 
// return timsetamps of the first and last message in the stream
DateTime[] range = stream.GetTimeRange();

// return timsetamps of the first and last message for the "EPAM" symbol
DateTime[] symbolRange = stream.getTimeRange(new ConstantIdentityKey("EPAM"));


Use rename() to change a stream key.

stream.rename("NewStreamKey");
stream.Rename("NewStreamKey");


Use delete() to remove the entire stream.

// delete entire stream and all data in the stream
stream.delete();
// delete entire stream and all data in the stream
stream.Delete();

Writing Data

TickStream API allows creating Loaders to write data into streams.

Reading Data

TickStream API allows creating Cursors to read from streams.

Pass to select() method such input parameters as start reading timestamp, selection options, message types and symbols you want to read from the stream. It is possible to dynamically change data subscription while reading stream data.

TickStream also allows renaming stream symbols:

IdentityKey[] from = new IdentityKey[] { new ConstantIdentityKey("DELTIX") };
IdentityKey[] to = new IdentityKey[] { new ConstantIdentityKey("EPAM") };
stream.renameInstruments(from, to);

Data Modification

Use below methods to modify stream data.

Use clear() command to clear all data recorded for specific symbols.

// clear all stream data
stream.clear();

// remove data for "APPL" only
IdentityKey[] identities = new IdentityKey[] { new ConstantIdentityKey("APPL") };
stream.clear(identities); 
// clear all stream data
stream.Clear();

// remove data for "APPL" only
IIdentityKey[] identities = new IIdentityKey[] { new ConstantIdentityKey("APPL") };
stream.Clear(identities); 


Use truncate () command to clear data after the defined timestamp. Truncate can be applied to the entire stream and specific symbols.


// truncating using current time
long timestamp = System.currentTimeMillis();

// truncate all stream data
stream.truncate(timestamp);

// truncate all data for "APPL" only
IdentityKey[] identities = new IdentityKey[] { new ConstantIdentityKey("APPL") };
stream.truncate(timestamp, identities);
DateTime time = DateTime.Now;

// truncate all stream data
stream.Truncate(time);

// truncate all data for "APPL" only
IIdentityKey[] identities = new IIdentityKey[] { new ConstantIdentityKey("APPL") };
stream.Truncate(time, identities);


Use purge() command to clear data before the defined time. Purge applies to the entire stream.

// purge all data older than 1 day
long timestamp = LocalDateTime.now().minusDays(1).toEpochSecond(ZoneOffset.UTC) * 1000;
stream.purge(timestamp);
DateTime time = DateTime.Now.AddDays(-1);
stream.Purge(time);


Use delete() command to clear stream data for specific symbols (applies to all symbols in case omitted) and within a defined time range. Please note, that if to is later than the stream END timestamp, the entire stream is deleted.

//from and to timestamps are inclusive values
stream.delete(fromTimestamp, toTimestamp, new IdentityKey[] { new ConstantIdentityKey("APPL") });
DateTime from = DateTime.Now.AddDays(-1);
DateTime to = DateTime.Now.AddDays(-2);
stream.Delete(from, to, new IIdentityKey[] { new ConstantIdentityKey("APPL") });

Stream Locking

TimeBase supports two stream locking types:

  • Read Lock, when acquired, guarantees that stream data is not going to change until lock is released. Multiple Read Locks can be acquired on a single stream, according to the number of readers.
	DBLock lock = null;
	try {
		lock = stream.lock(LockType.READ);
		// ... do stream read stream
		
	} finally {
		if (lock != null)
			lock.release();
	}
	
    // grabbing lock with timeout		
	
	DBLock lock = null;
	try {
		lock = stream.tryLock(LockType.READ, 30000); // 30 seconds to wait
		// ... do stream read stream
		
	} finally {
		if (lock != null)
			lock.release();
	}
	IDbLock streamLock = null;
	try
	{
		streamLock = stream.Lock(LockType.Read);
	}
	finally
	{
		if (streamLock != null)
			streamLock.Release();
	}
	
    // grabbing lock with timeout		
		
	try
	{
		streamLock = stream.TryLock(LockType.Read, 30000); // 30 seconds to wait
	}
	finally
	{
		if (streamLock != null)
			streamLock.Release();
	}
  • Write Lock is an exclusive right for a stream. When acquired, it is not possible to get a Read Lock or another Write Lock for this particular stream from another user. Write Lock allows modifying streams without anyone interfering in the process. It is possible to acquire a Write Lock only after all Read Locks are released.
	DBLock lock = null;
	try {
		lock = stream.lock(LockType.WRITE);
		// ... do stream read stream
		
	} finally {
		if (lock != null)
			lock.release();
	}
	
    // grabbing lock with timeout		
	
	DBLock lock = null;
	try {
		lock = stream.tryLock(LockType.WRITE, 30000); // 30 seconds to wait
		// ... do stream read stream
		
	} finally {
		if (lock != null)
			lock.release();
	}
	IDbLock streamLock = null;
	try
	{
		streamLock = stream.Lock(LockType.Write);
	}
	finally
	{
		if (streamLock != null)
			streamLock.Release();
	}
	
    // grabbing lock with timeout		
		
	try
	{
		streamLock = stream.TryLock(LockType.Write, 30000); // 30 seconds to wait
	}
	finally
	{
		if (streamLock != null)
			streamLock.Release();
	}


Locks are identified by the connection id, it means that when the connection is closed or dropped all locks owned by this connection are going to be released.

In both cases stream locking is made per stream.

Working with Spaces (Data Partitions)

On a TickStream level you can rename and delete spaces. Refer to Data Distribution to learn how to create spaces using option.space.

//rename spaces
stream.renameSpace("newName", "oldName");

//delete spaces
stream.deleteSpace("2019", "2020");
...

//get space metadata
// time range
long[] range = stream.getTimeRange("2020");

// entities (symbols)
InstrumentIdentity[] ids = stream.listEntities("2020");
//rename spaces
stream.RenameSpace("newName", "oldName");

//delete spaces
stream.DeleteSpace("2019", "2020");
...

//get space metadata
// time range
long[] range = stream.getTimeRange("2020");

// entities (symbols)
InstrumentIdentity[] ids = stream.ListEntities("2020");