Baechul's Weblog

• http://blogs.sun.com/clarkeman/entry/javafx_async_operations 
  

As a summary of old behavior, there was a built-in support for the remote text document to download in a non EDT thread. But this was just one of asynchronous usecases and couldn't be used for many other usecases. In the above blog, James showed how-to get around for the non remote text download case. But the workaround is still cumbersome and forced users to use some implementation classes at com.sun.javafx.runtime.async package.

New javafx.async in JavaFX 1.2

 Now JavaFX 1.2 javafx.async package comes with much clean design to support various asynchronous usecases. Please note that only supported usecase RemoteTextDocument class was removed in 1.2. It's still simple enough to have only 3 new classes namely 2 FX abstract classes(JavaTaskBase/Task) and 1 Java interface(RunnableFuture).

In most of cases, users are required to create their own 2 classes.

• A Java class(e.g. MyRunnable) that implements RunnableFuture interface. Simply complete the run() method that will be executed in a non-EDT thread by the JavaFX Asynchronous Framework. At this point of time, FX class that extends this interface is not accepted and may result in an exception thrown.
  
• A FX class(e.g. MyTask) that extends JavaTaskBase. Simply override the create() method and create/return the RunnableFuture implemented class in the above step. 

Once you create MyTask you can call its start() and stop() functions to control the background work. There are 2 callback function variables(onStart/onDone) and various read-only status variables(started/stopped/failed/causeOfFailure/succeeded/done) that will be set from the non-EDT thread in a different point of time as it progresses.

Here is the UML sequence diagram to illustrate what's happening inside.

What about "progress" from the background thread?  

You will notice JavaTaskBase has the progress related variables such as maxProgress, progress and percentDone. How those are used when I want to be notified the progress? Well the current API doc didn't mention much about it. So hope this will be useful at the moment. Here is my take.

 Let's create a sample that can illustrate new JavaFX Asynchronous Framework with progress. This sample has 2 buttons(start/stop) and the count label at the bottom. The actual counting will happen in a non-EDT java thread simulating a background work. The start button will initiate the counting and the cancel button will stop the counting from the background thread. If the cancel button is not pressed, the counting will be done at 100. And the counted data will be shown in he FX UI as shown here.

 It's your Task responsibility to manipulate setting the maxProgress at the beginning and updating the progress variables as it goes in the run() method. One interesting point is that the maxProgress can be easily set from the FX MyTask probably either in create() or start() function. However the FX variable, progress should be set from the Java MyRunnable class. How can we do that when FX object can't be directly assessed in a Java object?

 The trick is to create a Java interface called Progressable. Let MyTask implement Progressable interface as well.  Pass itself to the java MyRunnable as a Progressable, which is a java interface. The  Progressable interface has only one method, setProgress(val). MyRunnable java class should now be able to call Progressable.setProgress(val) as it goes.

Here is the Progressable interface:

public interface Progressable {
    void setProgress(long progress);
}

 Unfortunately this interface is not a part of javafx.async package. Please copy and paste it to your project source dir. Please note that MyTask is now implementing both JavaTaskBase and Progressable. The percentDone is automatically calculated when the progress is updated. 

 Here is the MyRunnable java class:

import javafx.async.RunnableFuture;
import com.sun.javafx.functions.Function0;

public class MyRunnable implements RunnableFuture {
    CountData counter;
    Progressable task;

    public MyRunnable(CountData cdata, Progressable pi) {
        counter = cdata;
        task = pi;
    }

    @Override
    public void run() throws Exception {
        while(counter.count < 100) {
            counter.count++;
            setProgress(counter.count);
            Thread.sleep(100);
        }
    }

    void setProgress(final long progress) {
        javafx.lang.FX.deferAction(new Function0<Void>() {
            @Override
            public Void invoke() {
                task.setProgress(progress);
                return null;
            }
        });
    }
}

 As all events should be dispatched in the EDT, FX.deferAction() has to be used to invoke MyTask.setProgress(progress). When FX.deferAction() is used, the passed function will be invoked from the EDT. 

 Here is the MyTask FX class:

import javafx.async.*;

public class MyTask extends JavaTaskBase, Progressable {
    public-init var countData: CountData;
    var peer: MyRunnable;

    override function create(): RunnableFuture {
        peer = new MyRunnable(countData, this);
    }

    override function setProgress(pro: Long) {
        progress = pro;
    }

    override public function start():Void {
        maxProgress = 100;
        progress = 0;
        super.start();
    }
}

 Here is another diagram to illustrate what's happening inside.

 Finally the illustrated sample NetBean project can be downloaded from here (JavaAsyncSample).

There are a couple of things worthwhile to mention at last. 

1. Tasks are expected to be executed one time (one call to start()  per instance of a Task).
2. JavaFX code should not be run from objects that support RunnableFuture interface. Some related discussion if you are interested in.
   

Have a fun with a threading in JavaFX 1.2.