C H A P T E R   6

Collections and Concurrency

When you know a thing, to hold that you know it; and when you do not know a thing, to allow that you do not know it;—this is knowledge.

—Confucius

After the fast-paced exploration of JavaFX layouts in Chapter 4 and JavaFX UI controls in Chapter 5, we refocus our attention on some of the lower-level facilities of JavaFX in this chapter.

Recall that in Chapter 3, “Properties and Bindings,” you learned about the Observable interface and one of its subinterfaces ObservableValue. In this chapter, we examine the other two subinterfaces of Observable—ObservableList and ObservableMap—rounding out the story of the Observable family of interfaces and classes.

We then cover concurrency in JavaFX. We explain the JavaFX threading model, pointing out the most important threads present in a JavaFX application. We look at the rules that you must follow to ensure your JavaFX application is responsive to user inputs and not locked up by event handlers that take too long to execute. We also show you how the javafx.concurrent framework can be used to offload long-running routines to background threads.

We conclude this chapter with two examples that show how a JavaFX scene graph can be embedded into a Swing application using JFXPanel, and how it can be embedded into an SWT application using FXCanvas, paying attention to how to make the JavaFX event thread play nicely with the Swing event dispatching thread.

Understanding Observable Collections

As we saw in Chapter 3, the Observable interface has three direct subinterfaces in JavaFX 2.0—the ObservableValue interface, the ObservableList interface, and the ObservableMap interface. We learned that the ObservableValue interface plays a central role in the JavaFX 2.0 Properties and Bindings framework.

The ObservableList and ObservableMap interfaces reside in the javafx.collections package, and are referred to as the JavaFX 2.0 observable collections. In addition to extending the Observable interface, ObservableList also extends the java.util.List interface, and ObservableMap extends the java.util.Map interface, making both genuine collections in the eyes of the Java collections framework. And you can call all the Java collections framework methods you are familiar with on objects of the JavaFX observable collection interfaces and expect exactly the same results. What the JavaFX observable collections provide in addition to the stock Java collections framework are notifications to registered listeners. Because they are Observables, you can register InvalidationListeners with the JavaFX observable collections objects and be notified when the content of the observable collections becomes invalid.

Each of the JavaFX observable collections interfaces supports a change event that conveys more detailed information of the change. We examine the JavaFX observable collections and the change events that they support in the following sections.

Understanding ObservableList

Figure 6-1 is an UML diagram showing the ObservableList and supporting interfaces.

Figure 6-1. Key interfaces that support the JavaFX observable list

To prevent clutter, we omitted the java.util.List interface from the diagram in Figure 6-1. The java.util.List interface is the other super interface of ObservableList. The following two methods on the ObservableList interface allow you to register and unregister ListChangeListeners:

• addListener(ListChangeListener<? super E> listener)
• removeListener(ListChangeListener<? super E> listener)

The following, additional, six methods on ObservableList make working with the interface easier:

• addAll(E... elements)
• setAll(E... elements)
• setAll(Collection<? extends E> col)
• removeAll(E... elements)
• retainAll(E... elements)
• remove(int from, int to)

The ListChangeListener interface has only one method: onChange(ListChangeListener.Change<? extends E> change). This method is called back when the content of the ObservableList is manipulated. Notice that this method’s parameter type is the nested class Change that is declared in the ListChangeListener interface. We show you how to use the ListChangeListener.Change class in the next subsection. For now, we look at a simple example illustrating the firing of invalidation and list change events when an ObservableList is manipulated.

Unlike the Java collections framework, where the public API contains both the interfaces, such as List and Map, and concrete implementations of the interfaces that you can instantiate, such as ArrayList and HashMap, the JavaFX observable collections framework provides only the interfaces ObservableList and ObservableMap, but not concrete implementation classes. To obtain an object of a JavaFX observable collections interface, you use the utility class FXCollections. In Listing 6-1, we obtain an ObservableList<String> object by calling a factory method on FXCollections:

We then hooked an InvalidationListener and a ListChangeListener to the observable list. The invalidation listener simply prints out a message every time it’s called. The list change listener prints out the content of the observable list. The rest of the program simply manipulates the content of the observable list in various ways: by calling methods on the java.util.List interface, by calling some of the new convenience methods added to ObservableList, and by calling the remove() method on an Iterator obtained from the observable list.

When we run the program in Listing 6-1, the following output is printed to the console:

Indeed, every call that we made in the code to change the content of the observable list triggered a callback on both the invalidation listener and the list change listener.

If an instance of an invalidation listener or a list change listener has already been added as a listener to an observable list, all subsequent addListener() calls with that instance as an argument are ignored. Of course, you can add as many distinct invalidation listeners and list change listeners as you like to an observable list.

Handling Change Events in ListChangeListener

In this section, we take a closer look at the ListChangeListener.Change class and discuss how the onChange() callback method should handle the list change event.

As we saw in the preceding section, for an ObservableList obtained by calling FXCollections.observableArrayList(),each mutator call—that is, each call to a single method that changes the content of the observable list—generates a list change event delivered to each registered observers. The event object, an instance of a class that implements the ListChangeListener.Change interface, can be thought of as representing one or more discrete changes, each of which is of one of four kinds: elements added, elements removed, elements replaced, or elements permuted. The ListChangeListener.Change class provides the following methods that allow you to get at this detailed information about the change:

• boolean next()
• void reset()
• boolean wasAdded()
• boolean wasRemoved()
• boolean wasReplaced()
• boolean wasPermutted()
• int getFrom()
• int getTo()
• int getAddedSize()
• List<E> getAddedSublist()
• int getRemovedSize()
• List<E> getRemoved()
• int getPermutation(int i)
• ObservableList<E> getList()

The next() and reset() methods control a cursor that iterates through all the discrete changes in the event object. On entry to the onChange() method of ListChangeListener, the cursor is positioned before the first discrete change. You must call the next() method to move the cursor to the first discrete change. Succeeding calls to the next() method will move the cursor to the remaining discrete changes. If the next discrete change is reached, the return value will be true. If the cursor is already on the last discrete change, the return value will be false. Once the cursor is positioned on a valid discrete change, the methods wasAdded(), wasRemoved(), wasReplaced(), and wasPermutted()can be called to determine the kind of change the discrete change represents.

Once you have determined the kind of discrete change, you can call the other methods to get more information about it. For addition, the getFrom() method returns the index in the observable list where new elements were added; the getTo() method returns the index of element that is one past the end of the added elements; the getAddedSize() method returns the number of elements that were added; and the getAddedSublist() method returns a List<E> that contains the added elements. For removal, the getFrom() and getTo() methods both return the index in the observable list where elements were removed; the getRemovedSize() method returns the number of elements that were removed; and the getRemoved() method returns a List<E> that contains the removed elements. For replacement, both the methods that are relevant for addition and the methods that are relevant for removal should be examined, because a replacement can be seen as a removal followed by an addition at the same index. For permutation, the getPermutation(int i) method returns the index of an element in the observable list after the permutation whose index in the observable list before the permutation was i. In all situations, The getList() method always returns the underlying observable list.

In the following example, we perform various list manipulations after attaching a ListChangeListener to an ObservableList. The implementation of ListChangeListener, called MyListener includes a pretty printer for the ListChangeListener.Change object, and prints out the list change event object when an event is fired.

In the preceding example, we triggered the four kinds of discrete changes in an observable list. Since no methods on an ObservableList will trigger a permutation event, therefore we used the sort() utility method from the FXCollections class to effect a permutation. We have more to say about FXCollections in a later section. We triggered the replace event twice, once with set(), and once with setAll(). The nice thing about setAll() is that it effectively does a clear() and an addAll() in one operation and generates only one change event.

When we run the program in Listing 6-2, the following output is printed to the console:

In all but the removeAll() call, the list change event object contains only one discrete change. The reason that the removeAll() call generates a list change event that contains two discrete changes is that the three elements that we wish to remove fall in two disjoint ranges in the list.

In the majority of use cases where we care about list change events, you don’t necessarily need to distinguish the kinds of discrete changes. Sometimes you simply want to do something to all added and removed elements. In such a case your ListChangeListener method can be as simple as the following.

Understanding ObservableMap

Although ObservableMap appears equivalent to ObservableList in the JavaFX observable collections framework hierarchy, it is actually not as sophisticated as ObservableList. Figure 6-2 is an UML diagram showing the ObservableMap and supporting interfaces.

Figure 6-2. Key interfaces that support the JavaFX observable map

To prevent clutter, we omitted the java.util.Map interface from the diagram. The java.util.Map interface is the other super interface of ObservableMap. The following methods on the ObservableMap interface allow you to register and unregister MapChangeListeners:

• addListener(MapChangeListener<? super K, ? super V> listener)
• addListener(MapChangeListener<? super K, ? super V> listener)

There are no additional convenience methods on ObservableMap.

The MapChangeListener interface has only one method: onChange(MapChangeListener.Change<? extends K, ? extends V> change). This method is called back when the content of the ObservableMap is manipulated. Notice that this method’s parameter type is the nested class Change that is declared in the MapChangeListener interface. Unlike the ListChangeListener.Change class, the MapChangeListener.Change class is geared towards reporting the change of a single key in a map. If a method call on ObservableMap affects multiple keys, as many map change events as the number of affected keys will be fired.

The MapChangeListener.Change class provides the following methods for you to inspect the changes made to a key.

• boolean wasAdded() returns true if a new value was added for the key.
• boolean wasRemoved() returns true if an old value was removed from the key.
• K getKey() returns the affected key.
• V getValueAdded() returns the value that was added for the key.
• V getValueRemoved() returns the value that was removed for the key. (Note that a put() call with an existing key will cause the old value to be removed.)
• ObservableMap<K, V> getMap()

In the following example, we perform various map manipulations after attaching a MapChangeListener to an ObservableMap. The implementation of MapChangeListener, called MyListener includes a pretty printer for the MapChangeListener. Change object, and prints out the map change event object when an event is fired.

When we run the program in Listing 6-3, the following output is printed to the console:

In the preceding example, notice that the putAll() call generated two map change events because the other map contains two keys.

Using Factory and Utility Methods from FXCollections

The FXCollections class plays a similar role in the JavaFX observable collections framework that the java.util.Collections class plays in the Java collections framework. The FXCollections class contains ten factory methods for ObservableList:

• ObservableList<E> observableList(List<E> list)
• ObservableList<E> observableArrayList()
• ObservableList<E> observableArrayList(E... items)
• ObservableList<E> observableArrayList(Collection<? extends E> col)
• ObservableList<E> concat(ObservableList<E>... lists)
• ObservableList<E> unmodifiableObservableList(ObservableList<E> list)
• ObservableList<E> checkedObservableList(ObservableList<E> list, Class<E> type)
• ObservableList<E> synchronizedObservableList(ObservableList<E> list)
• ObservableList<E> emptyObservableList()
• ObservableList<E> singletonObservableList(E e)

It contains three factory methods for ObservableMap:

• ObservableMap<K, V> observableMap(Map<K, V> map)
• ObservableMap<K, V> unmodifiableObservableMap(ObservableMap<K, V> map)
• ObservableMap<K, V> observableHashMap()

And it contains nine utility methods that are parallels of methods with the same name in java.util.Collections. They all act on ObservableList objects. And they differ from their java.util.Collections counterpart in that when they act on an ObservableList, care is taken to generate only one list change events whereas their java.util.Collections counterpart would have generated more than one list change event.

• void copy(ObservableList<? super T> dest, java.util.List<? extends T> src)
• void fill(ObservableList<? super T> list, T obj)
• boolean replaceAll(ObservableList<T> list, T oldVal, T newVal)
• void reverse(ObservableList list)
• void rotate(ObservableList list, int distance)
• void shuffle(ObservableList<?> list)
• void shuffle(ObservableList list, java.util.Random rnd)
• void sort(ObservableList<T> list)
• void sort(ObservableList<T> list, java.util.Comparator<? super T> c)

We illustrate the effects of these utility methods in Listing 6-4.

When we run the program in Listing 6-4, the following output is printed to the console:

Notice that each invocation of a utility method in FXCollections generated exactly one list change event.

Using the JavaFX Concurrency Framework

It is common knowledge nowadays that almost all GUI platforms use a single-threaded event dispatching model. JavaFX is no exception, and indeed all user interface events in JavaFX are processed in the JavaFX Application Thread. However, with multicore desktop machines becoming common in recent years (e.g., I'm writing this chapter on my three-year-old quad-core PC), it is natural for the designers of JavaFX to take advantage of the full power of the hardware by leveraging the excellent concurrency support of the Java programming language.

In this section, we examine important threads that are present in all JavaFX applications. We explain the role they play in the overall scheme of JavaFX applications. We then turn our attention to the JavaFX Application Thread, explaining why executing long-running code in the JavaFX Application Thread makes your application appear to hang. Finally, we look at the javafx.concurrent framework and show you how to use it to execute long-running code in a worker thread off the JavaFX Application Thread and communicate the result back to the JavaFX Application Thread to update the GUI states.

Identifying the Threads in a JavaFX Application

The program in Listing 6-5 creates a simple JavaFX GUI with a ListView, a TextArea and a Button, and populates the ListView with the names of all live threads of the application. When you select an item from the ListView, that thread's stack trace is displayed in the TextArea. The original list of threads and stack traces is populated as the application is starting up. And you can update the list of threads and stack traces by clicking the Update button.

This is a pretty minimal JavaFX GUI application. Before letting you run this program, we point out several features of the program.

First of all, make a mental note of the main() method:

You have seen this method several times already. This stylized main() method always appears in a class that extends the javafx.application.Application class. There is an overloaded version of the Application.launch() method that takes a Class object as the first parameter that can be called from other classes:

Therefore you can move the main() method to another class:

to achieve the same result.

Next, notice that the nested class Model builds up its data model, which consists of a list of all live threads and the stack traces of each thread, in its update() method:

This method is called once in the constructor of Model, which is called from the constructor of the JavaFXThreadsExample, and once from the event handler of the Update button.

When we run the program in Listing 6-5, the GUI in Figure 6-3 is displayed on the screen. You can explore the threads in this JavaFX program by clicking on each thread name in the list and see the stack trace for that thread in the text area. Here are some interesting observations:

• The “main” thread's call stack includes a call to com.sun.javafx.application.LauncherImpl.launchApplication().
• The “JavaFX-Launcher” thread's call stack includes a call to the constructor JavaFXThreadsExample.<init>.
• The “JavaFX Application Thread” thread's call stack includes the native method com.sun.glass.ui.win.WinApplication._runLoop().
• The “QuantumRenderer-0” thread's call stack includes the method com.sun.javafx.tk.quantum.QuantumRenderer$ObservedRunnable.run().

Now when you click the Update button and examine the call stack for the “JavaFX Application Thread” thread, you will discover that the event handler of the Update button is executed on the JavaFX Application Thread.

Figure 6-3. The JavaFXThreadsExample program

This little experiment reveals some of the architectural elements of the JavaFX runtime system. Although parts of this information include implementation details represented by, appropriately, classes in the com.sun hierarchy—therefore not to be used in code of normal JavaFX applications—it is nevertheless beneficial to have some knowledge of how the internals work.

The javafx.application.Application class provides life-cycle support for JavaFX applications. In addition to the two static launch() methods we mentioned earlier in this section, it provides the following life-cycle methods.

• public void init() throws Exception
• public abstract void start(Stage stage) throws Exception
• public void stop() throws Exception

The constructor and the init() method are called in the “JavaFX-Launcher” thread. The start() and stop() methods are called in the “JavaFX Application Thread” thread. The JavaFX application thread is part of the Glass Windowing Toolkit in the com.sun.glass package hierarchy. JavaFX events are processed on the JavaFX Application Thread. All live scene manipulation must be performed in the JavaFX Application Thread. Nodes that are not attached to a live scene may be created and manipulated in other threads until they are attached to a live scene.

The owner of the “QuantumRenderer-0” thread is the Quantum Toolkit that lives in the com.sun.javafx.tk.quantum package hierarchy. This thread is responsible for rendering the JavaFX scene graph using the Prism Graphics Engine in the com.sun.prism package hierarchy. Prism will use a fully accelerated rendering path if the graphics hardware is supported by JavaFX and will fall back to the Java2D rendering path if the graphics hardware is not supported by JavaFX. The Quantum Toolkit is also responsible for coordinating the activities of the event thread and the rendering thread. It does the coordination using pulse events.

Had the JavaFXThreadsExample program included media-playing, another thread named “JFXMedia Player EventQueueThread” would have shown up on the list. This thread is responsible for synchronizing the latest frame through the scene graph by using the JavaFX application thread.

Fixing Unresponsive UIs

Event handlers execute on the JavaFX application thread, thus an event handler takes too long to finish its work, the whole UI will become unresponsive because any subsequent user action will simply queue up and won't be handled until the long-running event handler is done.

We illustrate this in Listing 6-6.

This class stands up a simple UI with a rectangle with a pronounced Color.DARKGRAY stroke and a Color.LIGHTGRAY fill in the center of a BorderPane, and two buttons at the bottom labeled “Change Fill” and “Change Stroke.” The “Change Fill” button is supposed to toggle the fill of the rectangle between Color.LIGHTGRAY and Color.GRAY. The “Change Stroke” button is supposed to toggle the stroke of the rectangle between Color.DARKGRAY and Color.BLACK. When we run the program in Listing 6-6, the GUI in Figure 6-4 is displayed on the screen.

Figure 6-4. The UnresponsiveUIExample program

However, this program has a bug in the event handler of the “Change Fill” button:

The Thread.sleep(Long.MAX_VALUE) simulates code that takes a long time to execute. In real-life applications, this might be a database call, a web service call, or a piece of complicated code. As a result, if you click the “Change Fill” button, the color change is not seen in the rectangle. What is worse, the whole UI appears to be locked up: the “Change Fill” and “Change Stroke” buttons stop working; the close window button that is provided by the operating system will not have the desired effect. The operating system might also mark the program as “Not Responding,” and the only way to stop the program is to use the operating system's forced kill functionality.

To fix problems like this, we need to offload long-running code to worker threads and communicate the result of the long computation back to the JavaFX application thread in order to update the states of the UI so that the user can see the result. Depending on when you learned your Java, your answer to the first question of offloading code to worker threads may be different. If you are a long-time Java programmer your instinctive reaction might be to instantiate a Runnable, wrap it in a Thread and call start() on it. If you started with Java after Java 5 and learned the java.util.concurrent hierarchy of classes, your reaction might be to stand up a java.util.concurrent.ExecutorService and submit java.util.concurrent.FutureTasks to it. JavaFX includes a worker threading framework based on the latter approach in the javafx.concurrent package.

We examine the interfaces and classes in this framework in the next few sections, but before we do that we use the Runnable and Thread approach to offload computation to a worker thread. Our intention here is to highlight the answer to the second question of how to cause code to be run on the JavaFX application thread from a worker thread. The complete corrected program can be found in ResponsiveUIExample.java. Here is the new code for the event handler of the “Change Fill” button:

We have replaced the long sleep with code that executes in a worker thread. After sleeping for three seconds, the worker thread calls the runLater() method of the javafx.application.Platform class, passing it another Runnable that toggles the rounded corners of the rectangle. Because the long-running computation is done in a worker thread, the event handler is not blocking the JavaFX application thread. The change of fill is now reflected immediately in the UI. Because the Platform.runLater() call causes the Runnable to be executed on the JavaFX application thread, the change to the rounded corners is reflected in the UI after three seconds. The reason we have to execute the Runnable on the JavaFX application thread is that it modifies the state of a live scene.

The Platform class includes the following helpful utility methods.

• public static boolean isFxApplicationThread() returns true if it is executed on the JavaFX application thread and false otherwise.
• public static boolean isSupported(ConditionalFeature)  tests whether the execution environment supports a ConditionalFeature. Testable ConditionalFeatures include EFFECT, INPUT_METHOD, SCENE3D, and SHAPE_CLIP.
• public static void exit(),  if called after the application's start() method has been called, causes the application's stop() method to be executed on the JavaFX application thread before the JavaFX application thread and other JavaFX platform threads are taken down. If the application's start() method has not been called yet, the application's stop() method may not be called.

Now that we have solved our problem with Runnable and Thread and Platform.runLater(), it is time to see how we can use JavaFX's built-in worker threading framework to solve the problem in a more flexible and elegant way.

Understanding the javafx.concurrent Framework

The JavaFX worker threading framework in the javafx.concurrent package combines the versatility and flexibility of the Java concurrency framework introduced in Java 5 with the convenience of the JavaFX properties and bindings framework to produce an easy-to-use tool-set that is aware of the JavaFX application threading rules and also very easy to use. It consists of one interface, Worker, and two abstract base classes, Task<V> and Service<V>, that implement the interface.

Understanding the Worker Interface

The Worker interface specifies a JavaFX bean with nine read-only properties, one method named cancel(), and a state model and state transition rules. A Worker represents a unit of work that runs in one or more background threads yet has some of its internal states safely observable to the JavaFX application thread. The nine read only properties are as follows.

• title is a String property that represents the title of the task.
• message is a String property that represents a more detailed message as the task progresses.
• running is a boolean property that is true only when the Worker is in the Worker.State.SCHEDULED or Worker.State.RUNNING state.
• state is an Object property that represents the Worker.State of the task.
• totalWork is a double property that represents the total amount of work of the task. Its value is –1.0 when the total amount of work is not known.
• workDone is a double property that represents the amount of work that has been done so far in the task. Its value is –1.0 or a number between 0 and totalWork.
• progress is a double property that represents the percentage of the total work that has been done so far in the task. Its value is –1.0 or the ratio between workDone and totalWork.
• value is an Object property that represents the output of the task. Its value is non-null only when the task has finished successfully, that is, has reached the Worker.State.SUCCEEDED state.
• exception is an Object property that represents a Throwable that the implementation of the task has thrown to the JavaFX worker threading framework. Its value is non-null only when the task is in the Worker.State.FAILED state.

The preceding properties are meant to be accessed from the JavaFX application thread. It is safe to bind scene graph properties to them because the invalidation events and change events of these properties are fired on the JavaFX application thread. It is helpful to think of the properties through an imaginary task progress message box that you see in many GUI applications. They usually have a title, a progress bar indicating the percentage of the work that has been done, and a message telling the user how many items it has processed already and how many more to go. All of these properties are set by the JavaFX worker threading framework itself or by the actual implementation of the task.

The running, state, value, and exception properties are controlled by the framework and no user intervention is needed for them to be observed in the JavaFX application thread. When the framework wants to change these properties, it does the heavy lifting of making sure that the change is done on the JavaFX application thread. The title, message, totalWork, workDone and progress properties are updatable by the implementation code of the task by calling framework-provided protected methods that do the heavy lifting of making sure that the change is done on the JavaFX application thread.

Worker.State is a nested enum that defines the following six states of a Worker:

• READY (initial state)
• SCHEDULED (transitional state)
• RUNNING (transitional state)
• SUCCEEDED (terminal state)
• CANCELLED (terminal state)
• FAILED (terminal state)

The cancel() method will transition the Worker to the CANCELLED state if it is not already in the SUCCEEDED or FAILED state.

Now that you are familiar with the properties and states of the Worker interface, you can proceed to learn the two abstract classes in the JavaFX worker threading framework that implements this interface, Task<V> and Service<V>.

Understanding the Task<V> Abstract Class

The Task<V> abstract class is an implementation of the Worker interface that is meant to be used for one-shot tasks. Once its state progresses to SUCCEEDED or FAILED or CANCELLED, it will stay in the terminal state forever. The Task<V> abstract class extends the FutureTask<V> class, and as a consequence supports the Runnable, Future<V>, and RunnableFuture<V> interfaces as well as the Worker interface. The Future<V>, RunnableFuture<V>, and FutureTask<V> interfaces and class are part of the java.util.concurrent package. Because of this heritage, a Task<V> object can be used in various ways that befit its parent class. However, for typical JavaFX usage, it is enough to use just the methods in the Task<V> class itself, a list of which can be found in the Javadoc for the class. Here is a listing of these methods, excluding the read-only properties that were discussed in the preceding section:

• protected abstract V call() throws Exception
• public final boolean cancel()
• public boolean cancel(boolean myInterruptIfRunning)
• protected void updateTitle(String title)
• protected void updateMessage(String message)
• protected void updateProgress(long workDone, long totalWork)

Extensions of Task<V> must override the protected abstract call() method to perform the actual work. The implementation of the call() method may call the protected methods updateTitle(), updateMessage(), and updateProgress() to publish its internal state to the JavaFX application thread. The implementation has total control of what the title and message of the task should be. For the updateProgress() call, the workDone and totalWork must either both be –1, indicating indeterminate progress, or satisfy the relations workDone >= 0 and workDone <= totalWork, resulting in a progress value of between 0.0 and 1.0 (0% to 100%).

The two cancel() methods can be called from any thread, and will move the task to the CANCELLED state if it is not already in the SUCCEEDED or FAILED state. If either cancel() method is called before the task is run, it will move to the CANCELLED state and will never be run. The two cancel() methods differ only if the task is in the RUNNING state, and only in their treatment of the running thread. If cancel(true) is called, the thread will receive an interrupt. For this interrupt to have the desired effect of causing the task to finish processing quickly, the implementation of the call() method has to be coded in a way that will detect the interrupt and skip any further processing. The no-argument cancel() method simply forwards to cancel(true).

Listing 6-7 illustrates the creation of a Task, starting it, and observing the properties of the task from a simple GUI that displays all nine of the properties.

The Model nested class for this program holds a worker field of type Worker, and a shouldThrow field of type AtomicBoolean. The worker field is initialized to an instance of an anonymous subclass of Task<String> that implements its call() method by simulating the processing of 250 items at a 20-milliseconds-per-item pace. It updates the properties of the task at the beginning of the call and in each iteration of the loop. If an interrupt to the thread is received while the method is in progress, it gets out of the loop and returns quickly. The shouldThrow field is controlled by the View to communicate to the task that it should throw an exception.

The View nested class of this program creates a simple UI that has a ProgressBar at the top, a set of Labels at the center that display the various properties of the worker, and three buttons at the bottom. The contents of the Labels are bound to the various properties of the worker. The disable properties of the buttons are also bound to the state property of the worker so that only the relevant buttons are enabled at any time. For example, the Start button is enabled when the program starts but becomes disabled after it is pressed and the task execution begins. Similarly, the Cancel and Exception buttons are enabled only if the task is running.

When we run the program in Listing 6-7, the GUI in Figure 6-5 is displayed on the screen.

Figure 6-5. The WorkerAndTaskExample program after starting up

Notice that the progress bar is in an indeterminate state. The values of Title, Message, Value, and Exception are empty. The value of Running is false. The value of State is READY, and the values of Total Work, Work Done, and Progress are all -1. The Start button is enabled whereas the Cancel and Exception buttons are disabled.

After the Start button is clicked, the task starts to execute and the GUI automatically reflects the values of the properties as the task progresses. Figure 6-6 is a screenshot of the application at this stage. Notice that the progress bar is in a determinate state and reflects the progress of the task. The values of Title and Message reflects what is set to these properties in the implementation of the call() method in the task. The value of Running is true. The value of State is RUNNING, and the values of Total Work, Work Done, and Progress reflect the current state of the executing task: 156 of 250 items done. The Value and the Exception fields are empty because neither a value nor an Exception is available from the task. The Start button is disabled now. The Cancel and Exception buttons are enabled, indicating that we may attempt to cancel the task or force an exception to be thrown from the task at this moment.

Figure 6-6. The WorkerAndTaskExample program while a task is in progress

When the task finishes normally, we arrive at the screenshot in Figure 6-7. Notice that the progress bar is at 100%. The Title, Message, Total Work, Work Done and Progress fields all have values that reflect the fact that the task has finished processing all 250 items. The Running is false. The State is SUCCEEDED. And the Value field now contains the return value from the call() method.

Figure 6-7. The WorkerAndTaskExample program after the task succeeded

If, instead of letting the task finish normally, we click the Cancel button, the task will finish immediately and the screenshot in Figure 6-8 results. Notice that the Status field has the value CANCELLED now. The Value field contains the string we returned from the call() method when the thread was interrupted. When we catch the InterruptedException in the call() method, we have two choices of exiting from the method body. In the program in Listing 6-7, we chose to return from the method. That's why we see a Value string. We could also have chosen to exit from the method body by throwing a RuntimeException. Had we made that choice, the screenshot would have an empty Value field but with an non-empty Exception field. The state of the worker would have been CANCELLED either way.

Figure 6-8. The WorkerAndTaskExample program after the task has been cancelled

The final screenshot, Figure 6-9, shows what happens when the Exception button is clicked when the task is executing. We simulate an exception in the task by setting an AtomicBoolean flag from the JavaFX application, which the task then picks up in the worker thread and throws the exception. Notice that the status field has the value FAILED now. The Value field is empty because the task did not complete successfully. The Exception field is filled with the message of the RuntimeException that we threw.

Figure 6-9. The WorkerAndTaskExample program after the task threw an exception

Understanding the Service<V> Abstract Class

The Service<V> abstract class is an implementation of the Worker interface that is meant to be reused. It extends Worker's state model by allowing its state to be reset to Worker.State.READY. Although the Service<V> abstract class does not extend any other class or implement any interface other than Worker, it does include a field of type Task<V> and another one of type java.util.concurrent.Executor. In addition to the nine read only properties of the Worker interface, Service<V> has an additional read write property of type Executor called executor. Here is a listing of the rest of the methods of Service<V>:

• protected abstract Task createTask()
• public void start()
• public void reset()
• public void restart()
• public final boolean cancel()

Extensions of Service<V> must override the protected abstract createTask() method to generate a freshly created Task. The start() method can only be called when the Service<V> object is in the Worker.State.READY state. It calls createTask() to obtain a freshly minted Task, and asks the executor property for an Executor. If the executor property is not set, it creates its own Executor. It binds the Service<V> object's nine Worker properties to that of the Task's. It then transitions the Task to the Worker.State.SCHEDULED state, and executes the Task on the Executor. The reset() method can only be called when the Service<V>'s state is not Worker.State.SCHEDULED or Worker.State.RUNNING. It simply unbinds the nine Service<V> properties from that of the underlying Task and resets their values to fresh start-up values: Worker.State.READY for the state property, and null or “” or false or –1 for the other properties. The restart() method simply cancels the currently executing Task, if any, and then does a reset() followed by a start(). The cancel() method will cancel the currently executing Task, if any; otherwise it will transition the Service<V> to the Worker.State.CANCELLED state.

Listing 6-8 illustrates using an instance of an anonymous subclass of the Service<V> abstract class to execute Tasks repeatedly in its own Executor.

The preceding program is derived from the WorkerAndTaskExample class that we studied in the previous section. The Model nested class for this program holds a worker field of type Worker, a shouldThrow field of type AtomicBoolean, and a numberOfItems field of type IntegerProperty. The worker field is initialized to an instance of an anonymous subclass of Service<String> that implements its createTask() method to return a Task<String> whose call() method is implemented almost exactly like the Task<String> implementation in the last section, except that instead of always processing 250 items, it picks up the number of items to process from the numberOfItems property from the Model class.

The View nested class of this program creates a UI that is almost identical to that in the previous section but with some additional controls in the button panel. One of the controls added to the button panel is a TextField named numberOfItems. The model's numberOfItems IntegerProperty is bound to an IntegerBinding created with the textProperty() of the view's numberOfItems field. This effectively controls the number of items each newly created Task will process. The Start button is disabled only if the service is in the Worker.State.RUNNING state. Therefore you can click on the Start button after a task has finished.

The action handler of the Start button now resets the shouldThrow flag to false and calls restart() of the service.

The screenshots in Figures 6-10 to 6-14 are taken with the ServiceExample program under situations similar to those for the screenshots in Figures 6-5 to 6-9 for the WorkerAndTaskExample program.

Figure 6-10. The ServiceExample program after starting up

Figure 6-11. The ServiceExample program while a task is in progress

Figure 6-12. The ServiceExample program after the task succeeded

Figure 6-13. The ServiceExample program after the task has been cancelled

Figure 6-14. The ServiceExample program after the task threw an exception

As you can see from the preceding screenshots, the number that is entered into the text field does indeed influence the number of items processed in each run of the service, as is evidenced by the messages reflected in the UI in the screenshots.

Embedding JavaFX Scenes in Swing and SWT Applications

Having examined the threading paradigm of the JavaFX runtime and ways to execute code from the JavaFX application thread, we now look at how to make use of JavaFX scenes in Swing and SWT applications. JavaFX 2.0 supports embedding a JavaFX scene into a Swing application through the javafx.embed.swing package of classes. This is a pretty small package that includes two public classes: JFXPanel, and JFXPanelBuilder. The JFXPanel class extends javax.swing.JComponent, and as such can be placed in a Swing program just as any other Swing component. JFXPanel can also host a JavaFX scene, and as such can add a JavaFX scene to a Swing program.

However, this Swing program with a JavaFX scene embedded in it needs both the Swing runtime to make its Swing portion function correctly, and the JavaFX runtime to make the JavaFX portion function correctly. Therefore it has both the Swing Event Dispatching Thread (EDT) and the JavaFX Application Thread. The JFXPanel class does a two-way translation of all the user events between Swing and JavaFX.

Just as JavaFX has the rule that requires all access to live scenes to be done in the JavaFX Application Thread, Swing has the rule that requires all access to Swing GUIs to be done in the EDT. You still need to jump the thread if you want to alter a Swing component from a JavaFX event handler or vice versa. The proper way to execute a piece of code on the JavaFX Application Thread, as we saw earlier, is to use Platform.runLater(). The proper way to execute a piece of code on the Swing EDT is to use EventQueue.invokeLater().

In the rest of this section, we will convert a pure Swing program into a Swing and JavaFX hybrid program, and a pure SWT program into a SWT and JavaFX hybrid program. We start off with the Swing program in Listing 6-9, which is very similar to the ResponsiveUIExample program.

When the program in Listing 6-9 is run, the UI in Figure 6-15 is displayed. It is a JFrame holding three Swing components, a JComponent with overridden paint()and getPreferredSize()methods that makes it look like the rectangle we saw in the earlier program, and two JButtons that will change the fill and the stroke of the rectangle.

Figure 6-15. The NoJavaFXSceneInSwingExample program

Inasmuch as the custom-painted JComponent in NoJavaFXSceneInSwingExample is hard to maintain over the long run, we replace it with the JavaFX Rectangle. This is done by replacing the Swing code with the equivalent JFXPanel code. Here is the Swing code:

And here is the JFXPanel code:

The JFXPanel constructor bootstraps the JavaFX runtime system. We set the preferred size to the JFXPanel in order for it to be laid out correctly in Swing containers. We then constructed the scene graph on the JavaFX application thread and bound it to the model, which we changed into a JavaFX bean. Another set of changes that need to be made are in the ActionListeners of the two JButtons. Modifying the model triggers a change to the JavaFX rectangle, therefore the following code needs to be run on the JavaFX application thread:

The completed Swing JavaFX hybrid program is shown in Listing 6-10.

When the program in Listing 6-10 is run, the GUI in Figure 9-16 is displayed. You can't tell from the screenshot, but the rectangle in the center of the JFrame is a JavaFX rectangle.

Figure 6-16. The JavaFXSceneInSwingExample program

JavaFX 2.0.2 introduced the capability of embedding JavaFX scene into an SWT application through the javafx.embed.swt package of classes. It contains one public class FXCanvas. The FXCanvas class extends org.eclipse.swt.widgets.Canvas, and can be placed in an SWT program just like any other SWT widget. FXCanvas can also host a JavaFX scene, and can add a JavaFX scene to an SWT program.

Since both SWT and JavaFX uses the native platform's UI thread as their own event dispatching thread, the SWT UI thread (where a Display object is instantiated and where the main loop is started and where all other UI widgets must be created and accessed) and the JavaFX application thread are one and the same. Therefore there is no need to use Platform.runLater() or its SWT equivalent display.asyncExec() in your SWT and JavaFX event handlers.

The SWT program in Listing 6-11 is an SWT port of the Swing program in Listing 6-9.

When the program in Listing 6-11 is run, the UI in Figure 6-17 is displayed. It is a SWT Shell holding four SWT widgets, a Canvas with a PaintListener that makes it look like the rectangle we saw earlier, two Buttons that will change the fill and the stroke of the rectangle, and a Label widget that will show the location of the mouse pointer when the mouse is inside the rectangle.

Figure 6-17. The NoJavaFXSceneInSWTExample program

As we did with the Swing example, we replace the custom painted Canvas widget in the program NoJavaFXSceneInSWTExample with a JavaFX Rectangle. This is done by replacing the SWT code with the equivalent FXCanvas code. Here is the SWT code:

And here is the FXCanvas code:

We also changed the model into a JavaFX bean. The event listeners are changed in a natural way. The complete SWT JavaFX hybrid program is shown in Listing 6-12.

When the program in Listing 6-12 is run, the GUI in Figure 6-18 is displayed. The rectangle in the center of the SWT Shell is a JavaFX rectangle.

Figure 6-18. The JavaFXSceneInSWTExample program

Summary

In this chapter, we looked at JavaFX observable collections, the JavaFX worker threading framework, and embedding JavaFX scene in Swing and SWT applications to help you understand the following principles and techniques.

• JavaFX 2.0 supports two observable collection classes: ObservableList and ObservableMap.
• ObservableList fires Change events through ListChangeListener. ListChangeListener.Change may contain one or more discrete changes.
• ObservableMap fires Change events through MapChangeListener. MapChangeListener.Change represents the change of only one key.
• The FXCollections class contains factory methods to create observable collections, and utility methods to work on them.
• The main event processing thread in JavaFX applications is the JavaFX application thread. All access to live scenes must be done through the JavaFX application thread.
• Other important threads such as the prism rendering thread and the media event thread collaborate with the JavaFX application thread to make graphics rendering and media playback possible.
• Long-running computations on the JavaFX application thread make JavaFX GUIs unresponsive. They should be farmed out to background, or worker, threads.
• The Worker interface defines nine properties that can be observed on the JavaFX application thread. It also defines a cancel() method.
• Task<V> defines a one-time task for offloading work to background, or worker, threads and communicates the results or exceptions to the JavaFX application thread.
• Service<V> defines a reusable mechanism for creating and running background tasks.
• The JFXPanel class is a JComponent that can put a JavaFX scene into a Swing application.
• In a Swing JavaFX hybrid program, use Platform.runLater() in Swing event listeners to access the JavaFX scene, and use EventQueue.invokeLater(), or SwingUtilities.invokeLater() in JavaFX event handlers to access Swing widgets.
• The FXCanvas class is an SWT widget that can put a JavaFX scene into a SWT application.
• In an SWT JavaFX hybrid program, the SWT UI thread and the JavaFX application thread is one and the same.

Resources

Here are some useful resources for understanding this chapter's material:

• The JavaFX architecture page on the JavaFX tutorials site: http://docs.oracle.com/javafx/2.0/architecture/jfxpub-architecture.htm
• The original JavaFX worker threading framework write up on FX Experience: http://fxexperience.com/2011/07/worker-threading-in-javafx-2-0/
• The original JavaFX and SWT interoperability write up on FX Experience: http://fxexperience.com/2011/12/swt-interop/
• The JavaOne 2011 site has links to all presentation slides, including many about JavaFX: http://www.oracle.com/javaone/index.html