Get started with JAVA

To get started with our JAVA connector, our distribution package includes a sample program with source code allowing to connect and print out data from our feed. First, we will help you configure the sample program and test if your credentials and the feed is working properly. Second, we will guide you through the simple setup of its source code so you can make your own experiments quickly.

Distribution package structure

When unzipping our distribution package, you will see a folder with following structure:

├── feed-connector
|   |
│   └── ... stuffs for non java users ...
|
├── feed-java                                     # Containing stuffs for JAVA examples
│   ├── app                                       # Ready to run application
|   |   |
│   │   ├── conf                                  
│   │   │   ├── libSportConfig.json               # Configuration to be updated with your credentials
│   │   │   └── logback.xml
│   │   ├── data-feed-test.jar
│   │   └── run.bat                               # One click run file for the demo app
│   └── code                                      # Ready to import Eclipse project
│       ├── conf
│       │   ├── customStreamFilterConfig.json     # Configuration file for custom config file example
│       │   ├── libSportConfig.json               # Default configuration file
│       │   └── logback.xml
│       ├── src                                   # Example source code 
│       ├── .classpath
│       └── .project
└─── libs                                         # Library for the example projects and app

For the purpose of this Getting Started guide, we just need the feed-java folder. The main purpose of each folder is commented above.

Testing your credentials and connection

This is super simple. Input your username and password supplied to you into the app\conf\libSportConfig.json and then open run.bat in your console. The config file looks like

  {
    "username":"unity_username",          # To be replaced with real username
    "password":"unity_password",          # To be replaced with real password
    "uri":"http://feed.url.com",          # To be replaced with real connection end point
  }

If everything running correctly, you will see something similar to

Found 0 Matches
======================
Found 1013 Matches
======================
Found 1014 Matches
======================
Found 1015 Matches
======================
....

printed out to your console. The number of matches greater than zero indicates that your username and password is correct and you can receive data from our feed.

Trying out some code

Importing the project

You can find the sample project under feed-java/code folder. This is a pre-made Eclipse project that you can also use as the starting point for your project. Note that the folder feed-java/code/conf has been added as a source folder for the project so that configurations are available on the classpath.

To use the project, you can directly import it to Eclipse following the steps bellow.

Step 1 Select Import from Eclipse menu

alt text

Step 2 Select Existing projects into Workspace

alt text

Step 3 Browse to the code folder

alt text

After importing, you need to change conf\libSportConfig.json file within the project with your own credentials before running any of our examples.

Destructuring an example

The simplest example is consuming our feed without any filtering. The example NoFilterSubscriber illustrate the steps for consuming feed well. You will have to do a few things to get the feed data:

  • Create a sportfeed client. The client does all the network communication and conversion from bytes to our data structure.

        /* Creating factory before instantiating SportsFeedClient */
    SportsFeedFactory factory = new SportsFeedFactory();

    /* Create SportsFeedClient using default config file (located in conf folder - libSportsConfig.json) */
    SportsFeedClient client = factory.create();

    There are other ways of specifying configuration for a sportfeed client, you can read more here

  • Attach a view. A view represents a subset of the data you received from our feed. It allows you to filter data according to your application’s needs. In our example, we create a default view which doesn’t filter any data and it also works with the most generic data type IBetMatch.

        /*Creation of a feed view that push IBetMatch instances to your handler*/
    FeedView<IBetMatch> noFilterIBetMatchFeedView = client.view(IBetMatch.class);

    To understand more about feed view, you can read here

  • Attach a handler to the view. A handler is where you receive the actual data command.

        /*Another way of getting data from a view is polling it with view.snapshot()*/
    PushModeHandler myHandler = new PushModeHandler("handler-identifier");
    noFilterIBetMatchFeedView.register(myHandler);

    You implement the DeltaEventHandler interface and in here, you do data processing as you please. Our example PushModeHandler only prints out received data into a log file located at feed-java/code/logs/PushModeHandler.log.

    Note : Attached handlers are invoked on the same thread used by the network I/O that receive feed data. Hence, it is recommended that you don’t perform heavy processing here to avoid blocking the thread. For example, you should not perform blocking database queries from your handler.

    Read more about pushmode from here

  • Start the client

      /* Calling start will actually connect to the feed */
  client.start();

After these steps, you will observe the data being printed out in the log file through PushModeHandler. Using push mode you will receive fragments of data every time something changes. There is, however, another way of consuming data through polling the feed view only when you need the data. In our example, we do this by calling noFilterIBetMatchFeedView.snapshot(), which gives you all current data from the view:

    /* Regularly poll and print out some data */
    while (true) {
      int limit = 3;
      ISnapshot<IBetMatch> snapshot = noFilterIBetMatchFeedView.snapshot();
        Collection<IBetMatch> matches = snapshot.matches();
        System.out.print("There are currently " + matches.size() + " matches. ");
        System.out.print("Only printing "+limit+" matches/events/records\n");
        printMatches(matches,limit);
        /* Perform business logic on the list of matches */
        Thread.sleep(5000);
    }
Configuring the sportfeed client

The default way of creating a sport feed client is to call SportsFeedClient client = factory.create();. This will search for the the libSportConfig.json in class the application classpath. You can also specify a configuration file at a different location by doing:

    SportsFeedClient client = factory.createFromConfigFile("<path-to-custom-configuration-file>");

The most basic form of a configuration file contains only the credentials and the location of the feed.

    {
      "username":"username",
      "password":"password",
      "uri":"https://sf.olesportsresearch.com"
    }

The more complete form would allow you to additionally configure some basic filters for common use cases such as filter bookies, sports or odd types. It also allow configuring time to live which dictates the odd expiry when network errors occur. An example of a complete configuration is as following:

    {
      "username":"unity_username",
      "password":"unity_password",
      "uri":"https://sf.olesportsresearch.com",
      "bookFilter":["IBC","SBO"],           # List of bookies you want to receive
      "oddTypeFilter":["TODAY","LIVE"],      # List of odd types you want to receive
      "sportFilter":["SOCCER"],             # List of sports that you want to receive
      "ttlConfig": {
        "livettl": "5000",
        "todayttl": "15000",
        "earlyttl": "30000",
        "enableTtl": true
      }
    }

Filters set through this configuration are expected to be more performant than filters set programmatically inside code as you’ll see in this section. You can look at our StreamFilterConfigSubscriber.java example to see these filters in action.