com.dxfeed.event

Interface TimeSeriesEvent<T>

Type Parameters:

T - type of the event symbol for this event type.

All Superinterfaces:

EventType<T>, IndexedEvent<T>, Serializable

All Known Implementing Classes:

Candle, DailyCandle, Greeks, TheoPrice, TimeAndSale, Underlying

public interface TimeSeriesEvent<T>
extends IndexedEvent<T>

Represents time-series snapshots of some process that is evolving in time or actual events in some external system that have an associated time stamp and can be uniquely identified. For example, TimeAndSale events represent the actual sales that happen on a market exchange at specific time moments, while Candle events represent snapshots of aggregate information about trading over a specific time period.

Time-series events can be used with DXFeedTimeSeriesSubscription to receive a time-series history of past events. Time-series events are conflated based on unique index for each symbol. Last indexed event for each symbol and index is always delivered to event listeners on subscription, but intermediate (next-to-last) events for each symbol+index pair are not queued anywhere, they are simply discarded as stale events.

Timestamp of an event is available via time property with a millisecond precision. Some events may happen multiple times per millisecond. In this case they have the same time, but different index. An ordering of index is the same as an ordering of time. That is, an collection of time-series events that is ordered by index is ascending order will be also ordered by time in ascending order.

Time-series events are a more specific subtype of IndexedEvent. All general documentation and Event Flags section, in particular, applies to time-series events. However, the time-series events never come from multiple sources for the same symbol and their source is always DEFAULT.

Unlike a general IndexedEvent that is subscribed to via DXFeedSubscription using a plain symbol to receive all events for all indices, time-series events are typically subscribed to using TimeSeriesSubscriptionSymbol class to specific time range of the subscription. There is a dedicated DXFeedTimeSeriesSubscription class that is designed to simplify the task of subscribing for time-series events.

TimeSeriesEventModel class handles all the snapshot and transaction logic and conveniently represents a list of current time-series events ordered by their time. It relies on the code of AbstractIndexedEventModel to handle this logic. Use the source code of AbstractIndexedEventModel for clarification on transactions and snapshot logic.

Classes that implement this interface may also implement LastingEvent interface, which makes it possible to use DXFeed.getLastEvent method to retrieve the last event for the corresponding symbol.

Publishing time-series

When publishing time-series event with DXPublisher.publishEvents method on incoming TimeSeriesSubscriptionSymbol the snapshot of currently known events for the requested time range has to be published first.

A snapshot is published in the descending order of index (which is the same as the descending order of time), starting with an event with the largest index and marking it with IndexedEvent.SNAPSHOT_BEGIN bit in eventFlags. All other event follow with default, zero eventFlags. If there is no actual event at the time that was specified in subscription fromTime property, then event with the corresponding time has to be created anyway and published. To distinguish it from the actual event, it has to be marked with IndexedEvent.REMOVE_EVENT bit in eventFlags. IndexedEvent.SNAPSHOT_END bit in this event's eventFlags is optional during publishing. It will be properly set on receiving end anyway. Note, that publishing any event with time that is below subscription fromTime also works as a legal indicator for the end of the snapshot.

Both TimeAndSale and Candle time-series events define a sequence property that is mixed into an index property. It provides a way to distinguish different events at the same time. For a snapshot end event the sequence has to be left at its default zero value. It means, that if there is an actual event to be published at subscription fromTime with non-zero sequence, then generation of an additional snapshot end event with the subscription fromTime and zero sequence is still required.

Field Summary

Fields inherited from interface com.dxfeed.event.IndexedEvent

REMOVE_EVENT, SNAPSHOT_BEGIN, SNAPSHOT_END, SNAPSHOT_MODE, SNAPSHOT_SNIP, TX_PENDING

Method Summary

Modifier and Type	Method and Description
default long	getEventId() Deprecated. Use getIndex()
long	getIndex() Returns unique per-symbol index of this event.
IndexedEventSource	getSource() Returns a source identifier for this event, which is always DEFAULT for time-series events.
long	getTime() Returns timestamp of the event.

Methods inherited from interface com.dxfeed.event.IndexedEvent

getEventFlags, setEventFlags, setIndex

Methods inherited from interface com.dxfeed.event.EventType

getEventSymbol, getEventTime, setEventSymbol, setEventTime

Method Detail

getSource

IndexedEventSource getSource()

Returns a source identifier for this event, which is always DEFAULT for time-series events.

Specified by:

getSource in interface IndexedEvent<T>

Returns:

a source identifier for this event, which is always DEFAULT for time-series events.

getIndex

long getIndex()

Returns unique per-symbol index of this event. Event indices are unique within event symbol. Typically event index for a time series event includes time inside.

Implementation notes

The most common scheme for event indices is to set highest 32 bits of event index to event timestamp in seconds. The lowest 32 bits are then split as follows. Bits 22 to 31 encode milliseconds of time stamp, and bits 0 to 21 encode some kind of a sequence number.

Ultimately, the scheme for event indices is specific for each even type. The actual classes for specific event types perform the corresponding encoding.

Specified by:

getIndex in interface IndexedEvent<T>

Returns:

unique per-symbol index of this event.

getEventId

@Deprecated
default long getEventId()

Deprecated. Use getIndex()

Returns unique per-symbol index of this event.

Returns:

unique per-symbol index of this event.

getTime

long getTime()

Returns timestamp of the event. The timestamp is in milliseconds from midnight, January 1, 1970 UTC.

Returns:

timestamp of the event.

See Also:

System.currentTimeMillis()