Interface DynamicHistoryAccessInterface
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final longLargest number of blocks onegetLinearData(com.bookmap.api.treestructure.DataSource, velox.api.layer1.data.InstrumentInfo, com.bookmap.api.lineardata.LinearDataDescriptor<T>, java.lang.String, long, long)call may resolve to. -
Method Summary
Modifier and TypeMethodDescriptionget(long t1, long intervalWidth, int intervalNumber, com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo, List<com.bookmap.api.treestructure.TreeId> treeIds, DynamicHistoryAccessInterface.AsyncResultConsumer consumer) Requests historical data for a specific time interval and instrument.<T extends com.bookmap.api.Serializable>
CompletableFuture<LinearDataSlice<T>> getLinearData(com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo, com.bookmap.api.lineardata.LinearDataDescriptor<T> descriptor, String interval, long timeStartNanos, long timeEndNanos) Requests the finalized blocks of one linear data structure interval intersecting[timeStartNanos, timeEndNanos).<T> CompletionStage<T> getMetadata(com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo, MetadataType<T> metadataType) Provides metadata related to given instrument.
NOTE: Do not block or perform any heavy computation on the thread that completed CompletionStage. If you need to do that, use *Async or similar methods to offload the work to another thread.
Timestamps in the metadata (the first event time, a linear interval's first block start) are in the time the add-on sees, like the data itself: for a delayed instrument they are moved forward by the delay.
-
Field Details
-
LINEAR_DATA_MAX_BLOCKS_PER_REQUEST
static final long LINEAR_DATA_MAX_BLOCKS_PER_REQUESTLargest number of blocks onegetLinearData(com.bookmap.api.treestructure.DataSource, velox.api.layer1.data.InstrumentInfo, com.bookmap.api.lineardata.LinearDataDescriptor<T>, java.lang.String, long, long)call may resolve to. A request over this limit fails withLinearDataRangeTooLargeExceptionbefore any data is fetched. A slice is delivered whole, so the caller is responsible for keeping its size sane: for a wide time range use a coarser interval rather than many blocks of a fine one. For scale, 50,000 blocks is 35 days of a 1-minute interval and about 5.7 years of a 1-hour interval.- See Also:
-
-
Method Details
-
get
DynamicHistoryLoadingResult get(long t1, long intervalWidth, int intervalNumber, com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo, List<com.bookmap.api.treestructure.TreeId> treeIds, DynamicHistoryAccessInterface.AsyncResultConsumer consumer) Requests historical data for a specific time interval and instrument.
Request parameters are similar toDataStructureInterface.get(long, long, int, String, DataStructureInterface.StandardEvents[]), but instead ofaliasdataSourceandinstrumentInfopair is used, and instead ofStandardEvents[]List<TreeId>is used.
Returns theDynamicHistoryLoadingResultobject, containing events from thet1(inclusive) tot2 = t1 + intervalWidth * intervalNumber(exclusive).
Note: result object contain events from cache, but missing events are loaded asynchroniously and passed to the given consumer.
Note: this method was provided to look similar to DataStructureInterface, but in reality, the meaning of this request is: give me the events from [t0, t1) interval, so there at least one aggregated event in each pixel of intervalWidth size from this interval. Keep in mind that those blocks are precomputed so the t0 and t1 also not precise, as result
Time base: the request and everything it returns are in the time the add-on sees, i.e. the timegetCurrentTime()and live events are in. For a delayed instrument (InstrumentInfo.dataDelay) that is the time the data was shown, not the time it happened: Bookmap asks the server for the window moved back by the delay and moves the events it returns forward again, so history and live data meet without a gap. An add-on that converts its own aggregations is told the shift throughLayer1ApiDynamicHistoryListener.BlockContext.
Right border: intervals that end after the current time are dropped, since the server has nothing to serve for them, and a request that starts at or after the current time loads nothing.intervalWidthis kept as given, so the resolution of what is loaded does not change.- Parameters:
t1- Start time of the interval in nanoseconds, same as inDataStructureInterface. Must be non-negativeintervalWidth- Width of each interval in nanoseconds, same as inDataStructureInterface. Must be positiveintervalNumber- Number of intervals to load, same as inDataStructureInterface. But note there is no relation between final event count and intervalNumber. Must be positivedataSource- The data source from which to load the historical data. This parameter identifies the add-on source of the data.instrumentInfo- InstumentInfo of the instrument for which to load historical data.treeIds- List ofTreeIdobjects representing which trees do you want to load. All these trees are connected to the given data source and instrument.consumer- Consumer that will receive the updates as they are loaded.- Returns:
- A
DynamicHistoryLoadingResultobject containing the historical data for the specified time interval and instrument.
-
getMetadata
<T> CompletionStage<T> getMetadata(com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo, MetadataType<T> metadataType) Provides metadata related to given instrument.
NOTE: Do not block or perform any heavy computation on the thread that completed CompletionStage. If you need to do that, use *Async or similar methods to offload the work to another thread.
Timestamps in the metadata (the first event time, a linear interval's first block start) are in the time the add-on sees, like the data itself: for a delayed instrument they are moved forward by the delay.- Type Parameters:
T- metadata class- Parameters:
dataSource- The data source from which to get metadata. This parameter identifies the add-on source of the data.instrumentInfo- InstrumentInfo of the instrument for which to get metadata.metadataType- Type of metadata to get, seeMetadataTypefor details- Returns:
- requested metadata if possible, see
MetadataTypefor reasons why it can be unavailable
-
getLinearData
<T extends com.bookmap.api.Serializable> CompletableFuture<LinearDataSlice<T>> getLinearData(com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo, com.bookmap.api.lineardata.LinearDataDescriptor<T> descriptor, String interval, long timeStartNanos, long timeEndNanos) Requests the finalized blocks of one linear data structure interval intersecting[timeStartNanos, timeEndNanos). The range is clamped to the recorded data; the returned future completes with time-stamped blocks that tile the range. Quiet periods are ordinary blocks with an empty payload; blocks the server does not have at all (a hole between merged recordings, retention) appear asLinearDataSlice.Gapentries between the blocks. An unavailable structure or interval completes with an empty slice rather than failing.The server owns all time→index math (including calendar intervals such as months): the consumer only names the interval by its meta string and thinks in time. Returned blocks carry epoch-anchored absolute indices — a pure function of the block's period, identical in every recording — so they are safe to use as durable cache keys.
The range and the returned slice are in the time the add-on sees, like
get(long, long, int, com.bookmap.api.treestructure.DataSource, velox.api.layer1.data.InstrumentInfo, java.util.List<com.bookmap.api.treestructure.TreeId>, velox.api.layer1.dynamichistory.DynamicHistoryAccessInterface.AsyncResultConsumer): for a delayed instrument (InstrumentInfo.dataDelay) the server is asked for the range moved back by the delay, and every entry's bounds come back moved forward again. The decoded payloads are not touched;LinearDataSlice.dataDelayNs()tells the add-on what to add to any absolute timestamps inside them. The cataloggetMetadata(com.bookmap.api.treestructure.DataSource, velox.api.layer1.data.InstrumentInfo, velox.api.layer1.dynamichistory.metadata.MetadataType<T>)returns forMetadataType.linearMetadataType()is shifted the same way.- Type Parameters:
T- decoded block payload type.- Parameters:
dataSource- the data source the structure belongs to.instrumentInfo- the instrument to load.descriptor- identifies the structure and carries the serializer that decodes its blocks (the add-on defines its own descriptor).interval- the interval meta string to read (e.g."1m","1h","M"), as listed in the cataloggetMetadata(com.bookmap.api.treestructure.DataSource, velox.api.layer1.data.InstrumentInfo, velox.api.layer1.dynamichistory.metadata.MetadataType<T>)returns forMetadataType.linearMetadataType().timeStartNanos- start of the requested range, inclusive (epoch nanos).timeEndNanos- end of the requested range, exclusive (epoch nanos).- Returns:
- a future of the matching blocks. Never blocks the calling thread; the future is
guaranteed to complete — the resolve round-trip and every block batch are bounded by
the client's request timeouts and by a hard cap of ten minutes per server request.
Transient failures and timeouts complete it exceptionally and are retried on the next
call, never cached. Cancelling the future aborts the server requests it is still
waiting on; a cancelled load caches nothing. The future attempts completion on a
dedicated Bookmap executor for linear data; if that executor is saturated under heavy
load, completion falls back to the network thread to prevent task queue buildup.
Continuations attached without an explicit executor run on whichever thread completes
the future: keep them non-blocking, as slow callbacks will delay other linear data
handling or block the network I/O loop. A range that resolves to more than
LINEAR_DATA_MAX_BLOCKS_PER_REQUESTblocks completes the future exceptionally withLinearDataRangeTooLargeExceptionwithout fetching anything. Once the add-on has been unloaded (itsfinish()has run) the future completes exceptionally withIllegalStateException, again without contacting the server: loads already in flight at that point still complete, but no new ones are started. - Throws:
NullPointerException- if any reference argument isnull.IllegalArgumentException- ifintervalis blank ortimeEndNanos <= timeStartNanos. Argument errors are thrown synchronously, never delivered through the future.
-