The API Javadocs (IContext.executeTask) states:But the next code prove a different statement: the onMessage method is called from within the onTick method. A such behaviour is unexpected while API docs promise that the onMessage method will be executed AFTER the onTick method has exited. To see details run the code and look into it's output.

package jforex;

import com.dukascopy.api.*;
import java.io.PrintStream;
import java.util.EnumSet;

public final class TestThreading implements IStrategy {

    private final Instrument instrument = Instrument.EURUSD;
    private PrintStream out;
    private IEngine engine;
    private IOrder position;
    private boolean start;

    @Override
    public void onStart(IContext context) throws JFException {
        out = context.getConsole().getOut();
        engine = context.getEngine();
        context.setSubscribedInstruments(EnumSet.of(instrument), true);
        start = true;
    }

    @Override
    public void onTick(final Instrument instrument, ITick tick) throws JFException {
        if (instrument != this.instrument) return;
        if (start) {
            for (StackTraceElement e : Thread.currentThread().getStackTrace()) out.println(e);
            out.println("The 1st message");
            position = engine.submitOrder("label", instrument, IEngine.OrderCommand.BUY, 0.001);
            out.println("The 2nd message");
            position.waitForUpdate(IOrder.State.FILLED, IOrder.State.CANCELED);
            out.println("The 3rd message");
        }
    }

    @Override
    public void onBar(Instrument instrument, Period period, IBar askBar, IBar bidBar) throws JFException {}

    @Override
    public void onMessage(IMessage message) throws JFException {
        if (message.getOrder() == null || message.getType() == IMessage.Type.NOTIFICATION) return;
        if (message.getType() == IMessage.Type.ORDER_FILL_OK) {
            start = false;
            out.println("The 4th message");
            for (StackTraceElement e : Thread.currentThread().getStackTrace()) out.println(e);
            out.println("The 5th message");
        }
    }

    @Override
    public void onAccount(IAccount account) throws JFException {}

    @Override
    public void onStop() throws JFException { position.close(); }
}

I presume (since I've not tested it) that you are seeing 4th and 5th messages appearing before the 3rd. If so, this is as expected.

"the onMessage method is called from within the onTick method"

That's not accurate. The engine called onTick() and then onTick() handed control back to the engine and then the engine called onMessage() and then the engine resumed the execution of the existing onTick().

waitForUpdate(...) is a convenience call to simplify programming in use cases requiring a short pause/wait during state changes but it's also a disruptive call. Certainly disruptive to the engine's normal behaviour.

Question A
If we know we have a single thread and we know the IStrategy callbacks are made sequentially, what do we expect to happen if we introduce a call [of our own] within one of the callback methods [e.g. onTick()] that BLOCKS [e.g. Thread.sleep(5000)]?

Answer A
The engine comes to a complete halt until the BLOCK is removed.
Then it proceeds and as far as our strategy is concerned, the current tick would have occurred 5 seconds before the next one (ticks expected during the period of blocking lost).

So we already have onMessage() available to receive state changes, order submission is taking place in onTick(), these method names onXXXXX() hint that we're in an event driven environment. When something happens, a callback is made. Until something happens ideally we are doing nothing. No waiting. No polling. No sleeping. No blocking.

Above, the onTick() has been executed. Then a call is made to waitForUpdate(...). That means STOP right here in the middle of onTick() and wait here until the order state becomes X or changes from X to Y. Well, if we literally stop here the engine is dead and there will be no state changes. So waitForUpdate(...) is doing a bit more than a Thread.sleep(). It's informing the engine that I want to wait here but I need you to tell me when I can continue, to do that I want you to monitor the order states and return control to me when they become X or change from X to Y. The engine then takes back control for monitoring purposes (potentially making other useful callbacks* in the interim).

We already know that when the state changes happen we expect a call to onMessage(). It is beneficial (and an example of good programmer foresight) that calls to onMessage *prevail while onTick() is waiting.

We also know that onTick() isn't re-entrant, you can't have a new call made into onTick() while a previous one has yet to return. Therefore while waiting for the state change the engine is refusing to make further calls into onTick() while it deals with the request to monitor position states. Good foresight allows onMessage to still be called as the states change, allowing other areas of code to work despite a BLOCK in effect for onTick(). If it didn't happen this way, the waitForUpdate() would cause a Full Data and Information Blackout (instead of the current Partial one) for the entire strategy as nothing would happen until onTick() itself returned (whenever the user allowed it to). This is why the 4th and 5th messages MUST occur before the BLOCK is released.

And it is precisely to navigate disruptive BLOCKING by the user that waitForUpdate(...) is provided.
It co-ordinates things as best it can given the single threaded event-driven model the user sees and the same user's desire to wait for state changes right in the middle of single-threaded event-driven non-re-entrant callbacks.

Hope this helps.

Agree. 'Unexpected' means 'undocumented' in this case.

To Support Team: document this feature please.

It actually is documented in javadocs, but we are going to elaborate on it in order to help one better understand the multiple aspects of the waitForUpdate usage. In fact IOrder.waitForUpdate makes use of the Object.wait() -> Object.notify() paradigm (with customization regarding incoming ticks/bars).