New Implementation Best Practices

If you'd like to add a new exchange, broker, or market data provider to XChange, you've come to the right page. Here we outline the steps for creating a new implementation from the ground up. It's actually not too hard and there are already lots of examples to copy and paste from as you go.

Please fork and develop on the "develop" branch!

Step 1

Familiarize yourself with the data provider's API. What data is provided? What API do they have? In which format is the data returned? Do you need a login or key? Are there limitations on how often you can query the data? Create a file called api-specification.txt and take some notes.

Step 2

Create a new Maven module for the data provider. Update the pom.xml file using existing pom.xml files as a template.

Step 3

Get actual data and store it in a file in the project under test/resources. For example, see example-ticker-data.json. You can use http://jsonformatter.curiousconcept.com/#jsonformatter to format it nice.

To get the raw JSON returned from an API endpoint through XChange you first need a logback.xml file on your classpath. You can find an example logback.xml file in the xchange-examples module here: https://github.com/timmolter/XChange/blob/develop/xchange-examples/src/main/resources/logback.xml. Make sure the following line is UNCOMMENTED:

<logger name="si.mazi.rescu" level="TRACE" />

You will then find the returned raw JSON logged to the console on the line beginning like this:

si.mazi.rescu.HttpTemplate - Response body: 

Step 4

For each data file, create a corresponding Java object (DTO) that will contain all the data in the file. You can use http://www.jsonschema2pojo.org/ to speed up the process. Oh, and make it immutable (see BitstampTicker.java). There are examples of how to create DTOs that Jackson can unmarshall JSON into of varying complexity throughout the XChange project, so just look around for examples.

Step 5

Create JUnit tests to verify that the raw JSON to unmarshalled DTO works. See TickerJSONTest.java. The project uses FEST assertions, so please use these as well. Here is a link which shows lots of FEST assertion examples.

Name all test classes with the following pattern: *"DTO class name"*Test.java, e.g. CoinfloorOrderbookTest.java.

Step 6

Then you create an adapter class to take the provider-specific DTO (a raw DTO) and convert it into an XChange DTO. See BitstampAdapters.java.

And unit test that too (see BitstampAdapterTest.java)!

Step 7

Put it all together in two exchange service classes, such as BitstampMarketDataService.java and BitstampMarketDataServiceRaw.java. The *Raw class should fetch the JSON and deserialize it into exchange-specific DTOs. The non-*Raw class should use the *Raw class to get the exchange-specific DTOs and convert them to XChange-specific DTOs. Create an *Adapter class for adapting DTOs. Also catch all exchange-specific Exceptions in the *Raw class and re-throw them as ExchangeExceptions. Exchange-specific Exceptions should NOT be leaked out of the generic interface.

Step 8

In the module "xchange-examples", add example classes to demo the new exchange API capabilities. See TickerDemo.java.

Step 9

Create a single integration test class with a minimum of one test method that polls for a ticker at the exchange. This acts as an integration test for the exchange and catches any problems with the exchange itself. To run all unit tests WITHOUT running the integration test use mvn clean test. To run all unit tests WITH the integration test use mvn clean verify.

Name all integration test classes with the following pattern: *"DTO class name"*Integration.java, e.g. CoinfloorOrderbookTest.java.

Step 10

Format the Code with the provided XChange code style format profiles.

Step 11

Submit a pull request against the develop branch.

Step 12

Update the Exchange Support page.

A Note About Error Handling

The REST client that XChange uses (ResCU) provides a nice mechanism for handling returned JSON that has a different format than the expected valid JSON. See this Wiki page for more information.

Some "Rules" to Follow for Consistency

1. Never set a Date field in a DTO to new Date(). The timestamp fields represent "server" timestamps and not a client computer's system time.