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

Welcome to the third part of the JForexUtils documentation.
In case you missed previous parts:
Part 1
Part 2
All project links are listed at the end of this article.

In this part we will cover the very central context of order submission and change.
The tools for these tasks are easy to use and can be configured for complex scenarios.
All examples can be downloaded as a java file in the ExamplePart3.

Class OrderUtil
This important class handles all order creations and changes.
In Part 2 we've seen how to create an OrderParams object which holds all parameters for an order.
Let's start to use this orderParams object to open a new order:
1)Submit new order to server

This was fairly easy with the help of the orderParams object!
In the first line we create the orderUtil instance and in the second line we pass our previously created orderParams object to the submit method.
This is the minimal use case for opening a new order.

You may have a few questions though:
Q1 Where is the created order?
Q2 What if an exception was thrown; where is it and aren't we supposed to catch it?
Q3 What if the submission was rejected by the server?
Q4 Can I submit orders on a thread which is different from the strategy thread?

We'll answer all these questions in sequence.
As said before, this example is minimal; you can do it like that but you don't know if the submission and acceptance of the order by the server was successful or not.
The key is that the submit method returns an OrderCreateResult object.
This object contains information about the order submission state.
Let's see how we can extend the first example:

Line 1) The submit method is called as before, but this time we explore the returned OrderCreateResult instance.
Line 2-5) Here we check if an excpetion occured and if so do some proper error handling. The result object provides an Optional accessor.
Line 6-7) If no exception was thrown we can be sure that the order was created(but not yet opened by the server since this takes some time). To get the created order we call orderOpt().get() on the result object which provides an Optional accessor method.

As an alternative, you can use the orElse method of Optional to get the order instance or null if an excpetion occured.
This is shorter way of retreiving the created order, but it's a matter of taste which implementation style you prefer:

Here we check if the order is null and if so again evaluate the exception which is present in the result object.
To recap: the created order and possible exceptions can be retreived from the OrderCreateResult object which gives you information about the immediate outcome of an order submission.
All this should now answer questions Q1 and Q2.

So far we just submitted an order to the server and evaluated the immediate outcome, but we did not care about the server responses.
JForexUtils monitors all IMessage callbacks and evaluates these to see all order related messages.
If we want to react upon the server responses we need to enhance our submit call a bit more.
Class OrderUtil provides two overloads of the submit method which take additional callback objects.
With these callbacks we will get informed about all order changes as soon as they become available, so no need to wait/block your thread!
Let's how this works:

2)Submit order to server with callback object for order event notification
To receive all order events we first have to implement the OrderEventConsumer interface which has one method void onOrderEvent(final OrderEvent orderEvent).
Here's an example implementation of OrderEventConsumer which just prints the received order events:

You see that MyEventConsumer implements OrderEventConsumer and evaluates the passed OrderEvent object.
This object provides access to the order and a so called OrderEventType enum constant which represents all possible order events(you should explore OrderEventType with your IDE).
In this example we switch-case the event type and react upon successful order submission and fill.
You can insert your custom handlers here or react upon other event types you are interested in.

With the help of our MyEventConsumer class, we can now submit the orderParams object together with this order event handler:

This is it! With very few lines we've created an implementation which is reactive to all order events instead of doing ugly blocking/waits on the strategy thread.
Some remarks:
JForexUtils forces us to decouple the creation of an order from the evaluation of order events.
This helps in writing code which is moremodular and reusable(imagine for example you will need your implementation of OrderEventConsumer in many places).
Be aware that the interface OrderEventConsumer has only one method. This allows us for passing Java8 lambdas to the submit method as soon as JForex will fully support Java8(JForexUtils is future-ready ).

If you don't like big switch-cases and put all event logic in one place, there exists a second overload of the submit method which takes a map of OrderEventConsumer instances.
These instance will now get informed only about a specific order event and keeps the handling logic small.
Here's an example which implements two versions of OrderEventConsumer:
[img class= src=][

Now we can create a map which defines which order events will be routed to which instance of OrderEventConsumer:
[img class= src=]

Here we defined that an event type SUBMIT_OK will be forwared to the SubmitHandler instance and the event type SUBMIT_REJECTED will be forwared to the SubmitRejectHandler instance.
This is the most fine-grained control we can get to react upon order event types and all this stuff should now answer question Q3.

The last question remains about order submission on different threads.
Let's create a thread and submit an order:
[img class= src=]

[img class= src=]

So, in case of threading can you spot the difference? There is no difference, you don't need to obey anything when working with class OrderUtil on different threads!
You just submit your order and forget about the complex stuff which the Dukascopy Wiki describes here.
No need to create Callable taks, no need to call on IEngine, all this is done for you behind the scenes and hence answers our last question Q4.

This is it for part 3 of the article series. We covered a lot of ground with the class OrderUtil to see how to submit an order.
In the upcoming part 4 we will continue on this path and see how all other order operations like merge, set SL/TP etc. work, so stay tuned

Project links:
Translate to English Show original