Bookmap Layer 0 API
General overview of L0 API
Bookmap API consists of 2 main parts:
- L0 API - allows you to feed raw data into Bookmap
- L1 API - used for building indicators/strategies and feeding processed data into Bookmap
This repository contains examples of L0 API usage. For L1 API, visit
the DemoStrategies repository
Use cases
Layer0 API is a relatively simple way to:
- Replay your own file format with Bookmap - referred to as Replay modules.
- Connect Bookmap to your own data source in real-time (both for receiving data and
trading) - referred to as Live modules
Doing that requires basic Java knowledge, however (1) is possible even without any Java
knowledge at all using any programming language if you don’t mind converting files before
playing instead of integrating format support into Bookmap platform.
Code examples
Layer0ApiDemo project provides 4 demo classes with detailed comments that illustrate the most
typical scenarios:
DemoTextDataReplayProvider - loads simple text format into Bookmap. As an option,
you can just generate a file in this format and feed it to Bookmap using this module. This
enables using any language for conversion to Bookmap format.
DemoGeneratorReplayProvider - mimics a replay provider, but instead of loading data
this provider generates it. Example of setting order queue position and displaying simple
indicators using legacy API.
DemoExternalRealtimeProvider - example of custom realtime data provider. This one
only generates random data for illustration purposes, but you can use it to build your
own connectivity.
DemoExternalRealtimeTradingProvider - extends DemoExternalRealtimeProvider
providing trading capability. Simulates limit orders over the generated data. Shows how
to build your own provider for connecting to a platform with trading support.
The project also contains some more complicated examples.
Javadoc
Javadoc is available in:
-
Bookmap Maven repository -
open a directory with a name that corresponds to your Bookmap version (available at Help -> About).
Download the file api-core-<your_version>-javadoc.jar, where <your_version> is the version of
your Bookmap.
-
Use the javadoc bundled with your Bookmap - bm-l1api-javadoc.jar typically located
in C:\Program Files\Bookmap\lib
(location might differ depending on the path selected during installation).
The javadoc contains documentation for all levels of API, but for L0 API it’s mostly sufficient to
only look inside velox.api.layer0 package.
Developing your L0 module
The good starting points for your L0 modules are the classes:
ExternalLiveBaseProvider - for Live modules
ExternalReaderBaseProvider - for Replay modules
Extending those classes will provide some parts of the logic already implemented for you.
It’s also highly advised to read the javadoc for these classes, as it describes the L0 modules lifecycle.
Loading modules
There are 2 ways to load modules.
1. Loading via configuration files
This approach is recommended for development, as it allows loading class files directly, without
building a jar file.
For Bookmap to load your module, it should be added to a configuration file inside
C:\Program Files\Bookmap\lib\UserModules\L0
There are 2 files, external-live-modules.txt and external-reader-modules.txt
The first one contains a list of live connectivity modules, and the second one contains a list of
replay modules.
Files can contain comment lines (start with #) and lines in the following format:
<full-class-name> <path-without-spaces>
The path can point to either folder or .jar file with classes, whatever is more convenient.
For example, the line in external-live-modules.txt can look like this:
velox.api.layer0.live.DemoExternalRealtimeTradingProvider D:\Layer0ApiDemo\build\classes\java\main\
Note that for this approach to work all the files should be included into the
folder/jar file that you specify as <path-without-spaces>, i.e. if your module uses
a file from resources folder of class path - make sure it is in the same folder.
2. Loading from a jar file
Modules annotated with @Layer0LiveModule or @Layer0ReplayModule can be
packed into the JAR file and placed in C:\Bookmap\API\Layer0ApiModules (or similar location if
the path was changed during the installation process). Bookmap will load it automatically on
startup, as
long as it’s permitted by license.
Using the modules
After modules are configured, those are used similarly to Bookmap internal functionality.
1. Using Replay modules
Select a file the same way you would open a Bookmap feed file. Note, that since the extension of
your file
will likely be different from .bmf, you should first type “*” into the file name field and press
enter -
this will reset the file type filter and will allow you to load any type of file.
2. Using Live modules
Navigate to Connections -> Configure, and select your module from the Platform dropdown. Fill username,
password fields, connect the same way you would do with any other connection.
If you don’t need username or password just leave those empty - actual use of that data will be
defined by your code.
If you need to place some additional data like server address, you can place it into one of those
fields. E.g. user “u1” at server “127.0.0.1” could be set as u1@127.0.0.1 inside “username” field.
Use Layer0CredentialsFieldsManager annotation if you want to customize the input fields.
Environment setup
Check out IDE and tricks
for more details about running your project from IDE - the process and the main caveats are similar.
Modifying the example project
The repository contains a gradle project which you can import into an IDE of your choice.
Make sure you have Bookmap installed (using the default path will make things a bit more simple),
then import the example Layer0ApiDemo project as a gradle project.
Use gradle build command for building the classes, or gradle jar to build the jar file (
available
in build/libs/)
Creating your own project
For your own project, you can copy the build.gradle file to a new folder and create src\main\java
and src\main\resources folders near it.
If you don’t want to use gradle, you can just use API (either from C:\Program Files\Bookmap\lib\bm-l1api.jar or downloaded from the repository) as a compile-time
dependency and build classes or jar file in any other way.