JForexUtils - A collection of useful java classes for JForex - Part1

Dear JForex programmers,

if you have ever felt that strategy programming in JForex is sometimes a cumbersome task, then you will find some help in this and upcoming articles.
I've developed a Java library with lots of tools which greatly simplifies strategy development.
I share this library with you and will describe its features and use cases.
As a preview here are some of the major features you will be able to use:

* Useful tools for creating currencies and instruments
* A very easy to use builder for order parameters
* A powerful class for all order submission or changes. It is thread safe and you can send order commands directly from all threads with one consistent API
* With the help of a calculation tool you can do pip math tasks, convert order amounts etc.
* Quote classes provide an easy way to get the latest ticks/bars. They are also very fast which pays off when doing long backtests
* The most complex class is able to do a merge operation in one go!

Hopefully this preview has quicken your appetite
Please obey these prerequisites:
    This article series is for experienced(!!) JAVA/JForex programmers, so you should know how to add jar files to your build path, set up your IDE, install the correct JVM etc.

    JForexUtils is written in Java8 which requires a Java8 JVM; be aware that JForex client does currently not support Java8, so as of now you cannot use streams, lambdas etc. within in your strategies

    As of now, the library uses JForex API 2.12.30 so make sure you have this version installed(or a newer one)

    Only Forex instruments are supported, no options, stocks or other stuffUnfortunately, this BBCode editor does not support code snippets, so I must insert pictures as code examples(excuse me for the minor quality)

    I give no warranty whatsoever about bugs in the library; however, I'm using it since years and have the impression that no major bugs are present; please conduct backtests in the historical tester to see if it works for you without flaws

    The project and its source code can be found at GitHub; you can report issues/problems there

    All important project links can be found at the end of this article

Ok, lets get started
In order to get JForexUtils working, follow these steps:

1) Make sure you have a Java8 compatible JVM installed on your system
2) Download JForexUtils-0.9.35.jar
3) Add the downloaded JForexUtils-0.9.35.jar to your build path
4) Create a new project with your IDE and start with the skeleton strategy
5a) In case you are working on a standalone project: you must remove the @RequiresFullAccess and @Library lines.
5b) In case you work with the JForex client: replace @Library("D:/programs/JForex/libs/JForexUtils-0.9.35.jar") with your local path where you've saved the jar.
6) If everything went fine you should be able to compile this empty strategy

During this article series we will develop a full working example strategy which shows many aspects of JForexUtils.
We will start now with very simple classes; all code snippets can be found in the running example.

Class CurrencyBuilder
This class provides methods to create ICurrency instances from various sources.
All methods are static so you can use them everywhere anywhere(the class is thread safe).

1)Create ICurrency instances from currency name/string:

You can create instances from strings where lower or uppercase does not matter. The return type is an Optional in case you provided an invalid string. So you should check if the Optional is valid, and if so apply .get() to get the instance. For an invalid name you get an empty Optional back.

2)Create ICurrency instances from multiple currency names/strings:

As you see, the method fromNames is overloaded such that you can either provide any string collection of currency names or provide them directly without building a collection first.
In both cases you get a currency set back with "EUR", "CHF", "JPY" since "ouch" is not valid and will be discarded. If all names are invalid you get an empty set back(no need for a null check!).

3)Create ICurrency instances from instrument(s):

Here you see various examples where you get back a set of ICurrency instances which are contained in the given instrument(s). You provide either a single instrument, a collection or a comma separated list of instruments.
For example: the last line returns a set of ICurrency instances for "EUR", "USD", "CHF", "JPY" since these are the currencies which make up EUR/USD and CHF/JPY.

Class CurrencyUtil
This class might come handy when you want to perform some checks in the context of currencies.
All methods are static so you can use them everywhere anywhere(the class is thread safe).

1)Check if a currency name is valid:

This is trivial: it just checks whether a given currency name/string(not case sensitive) represents a valid currency code. Returns true if valid, false otherwise.

2)Checking if an instrument contains a currency

These examples show how you can check if a currency name/currency instances are contained in instrument(s). If you provide invalid currency names you always get false back. As an example, the second line returns false since "JPY" is not a currency of EUR/USD.

Class InstrumentBuilder
This class provides simple methods and combinatorics to create instrument(s). In conjunction with CurrencyBuilder you will see what can be achieved with very few lines.
All methods are static so you can use them everywhere anywhere(the class is thread safe).

1)Creating an instrument from name/string or from currencies

Line one creates valid instrument EUR/USD. Line two also, since you can invert the name. Line three returns an empty Optional since "EURUSD" misses the slash! Line 4 creates valid instrument GBP/AUD from the two currencies. You see here a use case for the previously discussed CurrencyBuilder. You can also provide the two currencies in reversed order.

2)Combining one anchor currency with partner currencies

This example demonstrates how you can build a set of instruments when you want an anchor/reference currency(here "EUR") to be combined with all partner currencies(here "EUR", "USD", "AUD", "JPY"). The resulting set contains the following instruments: EUR/USD, EUR/AUD, EUR/JPY. Obey that "EUR" in partner currencies is discarded since EUR/EUR is not a valid combination.

3)Combining several currencies to all possible instruments

Here you see how you can easily combine all currencies to all possible instruments. The resulting set contains the following instruments: EUR/USD, EUR/AUD, EUR/JPY, AUD/USD, AUD/JPY, USD/JPY. Imagine how awful this would be to construct them from scratch, or when you add much more currencies :-)
This is it for part 1 of the article series.
We've covered various helper tools to construct or validate currencies and instruments.
These tools will be needed in upcoming articles where it gets way more interesting, so stay tuned :-)

Project links:

Translate to English Show original