Oracle Blog

Blog for jtc

Wednesday Feb 10, 2010

When contemplating how machine-dependent applications might communicate with Java/JavaFX, JNI or the Java Native Interface, having been created for just such a task, would likely be the first mechanism that comes to mind. Although JNI works just fine thank you, a group of us ultimately decided against using it for a small project because, among others:

Errors in your JNI implementation can corrupt the Java Virtual Machine in very strange ways, leading to difficult diagnosis.

JNI can be time consuming and tedious, especially if there's a varied amount of interchange between the Native and Java platforms.

For each OS/Platform supported, a separate JNI implementation would need to be created and maintained.

Instead we opted for something a bit more mundane, namely sockets. The socket programming paradigm has been around a long time, is well understood and spans a multitude of hardware/software platforms. Rather than spending time defining JNI interfaces, just open up a socket between applications and send messages back and forth, defining your own message protocol. Following are some reflections on using sockets with JavaFX and Java. For the sake of simplicity, we'll skip the native stuff and focus on how sockets can be incorporated into a JavaFX application in a thread safe manner.

Sockets and Threading

Socket programming, especially in Java, lends itself to utilizing threads. Because a socket read() will block waiting for input, a common practice is to place the read loop in a background thread enabling you to continue processing while waiting for input at the same time. And if you're doing this work entirely in Java, you'll find that both ends of the socket connection -- the "server" side and the "client" side -- share a great deal of common code. Recognizing this, an abstract class called GenericSocket.java was created which is responsible for housing the common functionality shared by "server" and "client" sockets including the setup of a reader thread to handle socket reads asynchronously.

For this simple example, two implementations of the abstract GenericSocket class, one called SocketServer.java, the other called SocketClient.java have been supplied. The primary difference between these two classes lies in the type of socket they use. SocketServer.java uses java.net.ServerSocket, while SocketClient.java uses java.net.Socket. The respective implementations contain the details required to set up and tear down these slightly different socket types.

Dissecting the Java Socket Framework

If you want to utilize the provided Java socket framework with JavaFX, you need to understand this very important fact: JavaFX is not thread safe and all JavaFX manipulation should be run on the JavaFX processing thread.1 If you allow a JavaFX application to interact with a thread other than
the main processing thread, unpredictable errors will
occur. Recall that the GenericSocket class created a reader thread to handle socket reads. In order to avoid non-main-thread-processing and its pitfalls with our socket classes, a few modifications must take place.

Step 1: Identify Resources Off the Main Thread

The first step to operating in a thread safe manner is to identify those resources in your Java code, residing off the main thread, that might need to be accessed by JavaFX. For our example, we define two abstract methods, the first, onMessage(), is called whenever a line of text is read from the socket. The GenericSocket.java code will make a call to this method upon encountering socket input. Let's take a look at the SocketReaderThread code inside GenericSocket, to get a feel for what's going on.

Because onMessage() is called off the main thread and inside SocketReaderThread, the comment states that some additional work, which we'll explain soon, must take place to assure main thread processing.

Our second method, onClosedStatus(), is called whenever the status of the socket changes (either opened or closed for whatever reason). This abstract routine is called in different places within GenericSocket.java -- sometimes on the main thread, sometimes not. To assure thread safety, we'll employ the same technique as with onMessage().

Step 2: Create a Java Interface with your Identified Methods

Once identified, these method signatures have to be declared inside a Java interface. For example, our socket framework includes a SocketListener.java interface file which looks like this:

Step 3: Create Your Java Class, Implementing Your Defined Interface

With our SocketListener interface defined, let's take a step-by-step look at how the SocketServer class is implemented inside SocketServer.java. One of the first requirements is to import a special Java class which will allow us to do main thread processing, achieved as follows:

import com.sun.javafx.runtime.Entry;

Next, comes the declaration of SocketServer. Notice that in addition to extending the abstract GenericSocket class it also must implement our SocketListener interface too:

Next, let's examine the implementation of the two methods which are declared in the SocketListener interface. The first, onMessage(), looks like this:

/\*\*
\* Called whenever a message is read from the socket. In
\* JavaFX, this method must be run on the main thread and
\* is accomplished by the Entry.deferAction() call. Failure to do so
\* \*will\* result in strange errors and exceptions.
\* @param line Line of text read from the socket.
\*/
@Override
public void onMessage(final String line) {
Entry.deferAction(new Runnable() {
@Override
public void run() {
fxListener.onMessage(line);
}
});
}

As the comment points out, the Entry.deferAction() call enables fxListener.onMessage() to be executed on the main thread. It takes as an argument an instance of the Runnable class and, within its run() method, makes a call to fxListener.onMessage(). Another important point to notice is that onMessage()'s String argument must be declared as final.

Along the same line, the onClosedStatus() method is implemented as follows:

/\*\*
\* Called whenever the open/closed status of the Socket
\* changes. In JavaFX, this method must be run on the main thread and
\* is accomplished by the Entry.deferAction() call. Failure to do so
\* will\* result in strange errors and exceptions.
\* @param isClosed true if the socket is closed
\*/
@Override
public void onClosedStatus(final Boolean isClosed) {
Entry.deferAction(new Runnable() {
@Override
public void run() {
fxListener.onClosedStatus(isClosed);
}
});
}

Another Runnable is scheduled via Entry.deferAction() to run fxlistener.onClosedStatus() on the main thread. Again, onClosedStatus()'s Boolean argument must also be defined as final.

Accessing the Framework within JavaFX

With this work behind us, now we can integrate the framework into JavaFX. But before elaborating on the details, lets show screenshots of two simple JavaFX applications, SocketServer and SocketClient which, when run together, can send and receive text messages to one another over a socket.

These JavaFX programs were developed in NetBeans and utilize the recently announced NetBeans JavaFX Composer tool. You can click on the images to execute these programs via Java WebStart. Note: depending upon your platform, your system may ask for permission prior to allowing these applications to network. Source for the JavaFX applications and the socket framework in the form of NetBeans projects can be downloaded here.

Step 4: Integrating into JavaFX

To access the socket framework within JavaFX, you must implement the SocketListener class that was created for this project. To give you a feel for how this is done with our JavaFX SocketServer application, here are some code excerpts from the project's Main.fx file, in particular the definition of our ServerSocketListener class:

Sparing all of the gory details, the onMessage() method will place the line of text read from the socket in to a JavaFX ListView control which is displayed in the program user interface. The onClosedStatus() method primarily updates the local socketClosed variable and attempts to reconnect the socket if the autoconnect option has been selected.

To demonstrate how the socket is created, we examine the connectButtonAction() function:

Whenever the user clicks on the "Connect" button, the connectButtonAction() function will be called. On invocation, if the socket isn't already open, it will create a new SocketServer instance. Recognize also that the SocketServer constructor includes an instance of the ServerSocketListener class which was defined above.

To round this out, when the user clicks on the "Disconnect" button, the disconnectButtonAction() function is called. When invoked, it tears down the SocketServer instance.

Conclusion

Admittedly, there's a fair amount to digest here. Hopefully, by carefully reviewing the steps and looking at the complete code listing, this can serve as a template if you wish to accomplish something similar in JavaFX.