GWT: Timer and Scheduler Classes

I have read this page over several times, and am just not seeing some of the inherent differences between GWT's Timer and Scheduler classes. I'm looking for the use cases and applicability of each of the following:

• Timer, Timer::schedule and Timer::scheduleRepeating
• Scheduler::scheduleDeferred
• Scheduler::scheduleIncremental
• IncrementalCommand
• DeferredCommand

These all appear to be doing the same thing, more or less, and it feels like you can accomplish the same objectives with all of them. Is this just GWT's way a providing multiple ways of doing the same thing? If not, please help me understand when and where each is appropriately used.

Solution 1:

Use Scheduler when you need a browser to complete whatever it is currently doing before you tell it to do something else. For example:

myDialogBox.show();
Scheduler.get().scheduleDeferred(new ScheduledCommand() {

    @Override
    public void execute() {
        myTextBox.setFocus();
    }
});

In this example, focus will not be set until the browser completes rendering of the dialog, so you tell the program to wait until the browser is ready.

Use Timer if you want some action to happen after a specified period of time. For example:

 notificationPanel.show();
 Timer timer = new Timer() {
     @Override
     public void run() {
         notificationPanel.hide();
     }
 };
 timer.schedule(10000);

This code will show notificationPanel, and then it will hide it after 10 seconds.

Solution 2:

As the JavaDoc says, DeferredCommand is deprecated in favor of Scheduler. The problem with DeferredCommand and IncrementalCommand is that they have a static state (which makes it hard to use reliably in tests). Moreover, their (static) methods make JSNI calls which forces you to use a GWTTestCase to test your code (static methods aren't –easily– mockable). Static methods also make it impossible to wrap them (to, e.g. add some logging or whatever).
On the other hand, you work with an instance of a Scheduler (if you want testable code, you'll use dependency-injection to get a instance of a scheduler and will never call Scheduler.get() except in your DI "factory"). In a test, you can then use a StubScheduler for instance.

Then there's Timer, which is similar to the others but the scheduled task can be cancelled. Note that Timer makes use of JSNI too, just like DeferredCommand; any kind of code that uses a Timer will need a GWTTestCase to be unit-tested.