Package velox.api.layer1.dynamichistory

Interface DynamicHistoryAccessInterface

@DefaultQualifier(org.checkerframework.checker.nullness.qual.NonNull.class) public interface DynamicHistoryAccessInterface

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    DynamicHistoryAccessInterface.AsyncResultConsumer
     

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    <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).
    CompletableFuture<Optional<com.bookmap.api.lineardata.LinearDataMetadata>>
    getLinearDataMetadata(com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo)
    Discovers which linear data structures (per-interval block series, e.g.
    <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.

  • 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 to DataStructureInterface.get(long, long, int, String, DataStructureInterface.StandardEvents[]), but instead of alias dataSource and instrumentInfo pair is used, and instead of StandardEvents[] List<TreeId> is used.
      Returns the DynamicHistoryLoadingResult object, containing events from the t1 (inclusive) to t2 = 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
      Parameters:
      t1 - Start time of the interval in nanoseconds, same as in DataStructureInterface. Must be non-negative
      intervalWidth - Width of each interval in nanoseconds, same as in DataStructureInterface. Must be positive
      intervalNumber - Number of intervals to load, same as in DataStructureInterface. But note there is no relation between final event count and intervalNumber. Must be positive
      dataSource - 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 of TreeId objects 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 DynamicHistoryLoadingResult object 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.
      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, see MetadataType for details
      Returns:
      requested metadata if possible, see MetadataType for reasons why it can be unavailable

    • getLinearDataMetadata

      CompletableFuture<Optional<com.bookmap.api.lineardata.LinearDataMetadata>> getLinearDataMetadata(com.bookmap.api.treestructure.DataSource dataSource, InstrumentInfo instrumentInfo)
      Discovers which linear data structures (per-interval block series, e.g. zoom-out candles) the server has recorded for the given instrument, and — per interval — how many blocks exist and when the series starts. Use it to decide which structure/interval to request and to translate a time range into a request.

      Linear data is a separate data family from the trees requested via 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): there is no resolution, the interval meta string is the zoom selector, and each interval aggregates the raw stream independently.

      Never blocks the calling thread, and the returned future is guaranteed to complete: the fetch is bounded by the client's request timeouts plus a hard cap. It completes with Optional.empty() when the server permanently records no linear data for the instrument; a transient failure (server unreachable) completes the future exceptionally and is not cached — the next call retries.

      Parameters:
      dataSource - the data source the structures belong to (e.g. Bookmap original).
      instrumentInfo - the instrument to look up.
      Returns:
      a future of the per-alias catalog, or of Optional.empty() if the server records no linear data for this instrument.

    • 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 and fetched in server-sized batches; the returned future completes with dense, time-stamped blocks (gaps are present as empty payloads). 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.

      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 reported by getLinearDataMetadata(com.bookmap.api.treestructure.DataSource, velox.api.layer1.data.InstrumentInfo).
      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. Transient failures complete it exceptionally and are retried on the next call, never cached.