• Dec
    • 04
    • 2012

JavaFX with a SpringMVC REST server in 5 minutes

Posted by In Enterprise, JavaFX

Creating a simple JavaFX application in 5 minutes was pretty fun, but we can do better. This post shows you how to use the javafx-rest-archetype to create a skeleton project that includes both a REST server (based on SpringMVC) and a JavaFX client that talks to that REST server.

As before you need to have already installed JDK 7 (update 6) or later, and Maven 3.0 or later (make sure you set the JAVA_HOME environment variable when doing this).

Step 1: Fix your classpath

If you did this last time then you do not need to do it again!

When you install the JDK currently, it includes JavaFX but does not put it on the classpath (yes this is weird – it will be fixed in Java 8). To fix this, open a Command Prompt and type:

mvn com.zenjava:javafx-maven-plugin:1.3:fix-classpath

This will ask you to confirm that you want to do this, type “y”.

Step 2: Create a New Project

Open a command prompt and go to a new workspace area (i.e. create a new directory to house your code), then type:

mvn archetype:generate -DarchetypeGroupId=com.zenjava 
    -DarchetypeArtifactId=javafx-rest-archetype -DarchetypeVersion=1.1

You will be prompted for some parameters:

  • groupId: com.mycompany
  • artifactId: my-rest-app
  • version: leave as default
  • package: com.mycompany.myrest

This will create a new directory called “my-rest-project” with some basic source code which you can use as a skeleton to get you up and running quickly.

Step 3: Build the project

Change directory into your newly created project and use Maven to build your application – this will build both the client and server:

cd my-rest-app
mvn clean install

Step 4: Start the server

Change directory into the server sub-directory and start a Jetty server to run your REST web server:

cd my-rest-app-server
mvn jetty:run

You do not have to have Jetty installed, Maven will take care of this for you. Jetty is very useful for getting up and running quickly like this, however you don’t have to use Jetty. Maven builds a standard WAR file that you can deploy into any JEE web server, such as Tomact, JBoss, etc.

Your server should now be running. You can test it using a standard web browser to http://localhost:8080/my-rest-app-server/welcome and you should see XML output like:

Step 5: Run the client

Open a new command prompt, change directory into the client sub-directory and start your JavaFX client:

cd my-rest-app\my-rest-app-client
mvn jfx:run

When the JavaFX client starts up enter your name and hit the “Say Hello” button. The response from the server will be shown in the text area below:

Step 6: Edit your project

You now have a working skeleton project which you can build upon to create your next awesome JavaFX and REST server application. Since you are using Maven, you can simply open the base level POM file in your favourite IDE and your project will be automatically configured for you with the classpath all setup, etc.

Here’s the links again for using Maven with your IDE:

Your project tree should look something like (this is taken from IntelliJ):

Hopefully the code is pretty self explanatory, and I have included JavaDoc with links to external help documentation in most cases. If you need more help, post comments here or raise issues in the GitHub project for the archetype: https://github.com/zonski/javafx-rest-archetype/issues

Step 7: Distribute your app

Distributing your server is very easy, just take the generated WAR file from the ‘target’ directory of your server module and copy this to any JEE web server. I use and highly recommend Tomcat but you can use whatever you like. In tomcat simply download and install Tomcat (i.e. unzip it) onto your server and then copy the WAR file into the webapps directory. Tomcat will take care of the rest – server side deployment is easy these days.

As with the simple JavaFX application example, you can choose any of the JavaFX deployment options such as Webstart, native installer, executable JAR file, etc. They each have their advantages and disadvantages but refer to my previous post for details on this.

All the same commands are available as in the simple JavaFX project, just make sure you run them from within the client module. For example to build an executable JAR use:

cd my-rest-app\my-rest-app-client
mvn jfx:build-jar

And an executable JAR will be built into the target directory of the client module for you to copy and distribute however you want.

Conclusion

Using this archetype it is very easy to get up and running quickly with a simple JavaFX client and SpringMVC REST server. All of the code generated can be modified, added to and deleted to suit your own project needs so there are no dependencies or links to any special classes of my creation in the project. This simply provides a starting shell for you to do with as you please.

This example is deliberately simple. It does not include security or database setup, both of which would be pretty much standard in your typical REST client-server application. If I get time I and/or there is strong interest in seeing a REST setup with security and persistence, I may add an additional archetype. Register your interest in this by commenting below.

REST is very popular because it provides a way for JavaScript/AJAX clients to make remote calls on servers. I’ve provided this archetype because AJAX is such a popular space, however there are better, faster and simpler options than REST when working with pure Java on both the client and server, so why compromise? I am planning to create another archetype that creates the same setup as this one but using Spring Remoting based on Spring’s HTTPInvoker. Hopefully I will have something going on this over the next month or two – again register your interest by commenting if this is something you would find useful.

If you have any problems or suggestions please comment or raise an issue on the archetype GitHub project:  https://github.com/zonski/javafx-rest-archetype/issues

Continue Reading→
    • Nov
    • 24
    • 2012

From Zero to JavaFX in 5 minutes

Posted by In Enterprise, JavaFX

Over the last few weeks, I’ve been working on a new Maven Plugin for JavaFX. Using this plugin it’s much, much easier to get up and running quickly and to build complicated distribution bundles (such as executable JAR files, native installers and webstart bundles). Rather than tell you about it, here’s the steps to take you from nothing to a fully working, packagable JavaFX distribution.

Before starting you will need to have installed JDK 7 update 6 or later, and Maven 3.0 or later. This guide will walk you through that.

Step 1: Fix your Classpath

When you install the JDK currently, it includes JavaFX but does not put it on the classpath (yes this is weird – it will be fixed in Java 8). To fix this, open a Command Prompt and type:

mvn com.zenjava:javafx-maven-plugin:1.3:fix-classpath

This will ask you to confirm that you want to do this, type “y”.

You will need to do this only once for each development machine (and you will never need to do it on your users’ machines, only development ones).

Step 2: Create a New Project

Open a command prompt and go to a new workspace area (i.e. create a new directory to house your code), then type:

mvn archetype:generate -DarchetypeGroupId=com.zenjava /
-DarchetypeArtifactId=javafx-basic-archetype /
-DarchetypeVersion=1.1
You will be prompted for some parameters:
  • groupId: com.mycompany
  • artifactId: my-jfx-project
  • version: leave as default
  • package: com.mycompany.myjfx
This will create a new directory called “my-jfx-project” with some basic source code which you can use as a skeleton to get you up and running quickly.

Step 3: Run the Project

Change directory into your newly created project and use Maven to launch your application:

cd my-jfx-project
mvn jfx:run

You should see a basic hello world style dialog popup like so:

Note: this run command is just a pure wrapper around the maven exec plugin. There is no special JavaFX magic going on here, it’s just a convenience method.

Step 4: Edit the Project

You can now open the new project in your favourite IDE:

Since this a Maven application any dependencies you need will be downloaded, your classpath will be all setup for you and you simply can get stuck in and start editing, running and debugging your project.

The starter project includes some example FXML, basic logging and makes use of the very cool MigPane layout manager. All of this is just a guide, you can delete, edit, rename or do what you like to all of this code to create your perfectly customised JavaFX app.

Your project should look something like this, with MainApp being the main entry point that you run:

For tips on writing JavaFX applications see: http://docs.oracle.com/javafx/

For tips on using Maven to manage your dependencies: http://maven.apache.org/guides/getting-started/index.html

Step 5: Distribute your App

JavaFX applications can be deployed in a number of different ways – each option has it’s benefits and drawbacks - choose whichever option suits you.

Executable JAR file 

From the command line, and in the base directory of your project (where the POM file is) type:

mvn jfx:build-jar

Your executable JAR will be found at: {project.dir}/target/my-jfx-project-1.0-SNAPSHOT-jfx.jar

The Executable JAR file option is simple and handy as you can easily send the single JAR around to users and they can just double click it. It does require Java to be already installed on the user’s system though, and there’s no support for auto updating and advanced functions (like menu shortcuts, file associations, etc). Also be aware that if your jars contain files with the same name then they will clobber each other (see this issue)


‘BAT’ file (for Windows)

From the command line, and in the base directory of your project (where the POM file is) type:

mvn jfx:build-win-bat-bundle

A directory containing a Windows batch file  and all project JARs will be found at: {project.dir}/target/win-bat

The ‘BAT’ file option is great for quick demos, you can easily copy the directory to your demo machine and tweak the JAR files and scripts as needed. It does require Java to be already installed on the user’s system and java.exe being on the path, so it’s more for internal use than general end user consumption.


Webstart 

Webstart applications can either be signed, or unsigned. If they are not signed then they are limited by the browser’s sandbox. Most interesting applications will need to be signed and to do this you need to get a certificate to verify you are who you say you are.  For development this can be a pain, so the JavaFX Maven plugin includes the ability to generate a quick certificate for testing (i.e. you will be able to deploy but your users will see a “this app is not trusted” message when they run it).

To generate a certificate run the following command in the base directory of your project (change the domain, country code and state to match your details):

mvn jfx:generate-key-store -DcertDomain=com.yourcompany -DcertCountry=US -DcertState=WASHINGTON

You only need to do this once for your project and you can optionally check this development keystore into your source control so other developers can avoid this step.

To then build a Webstart bundle run:

mvn jfx:build-webstart

A directory containing  a HTML file, JNLP file and your signed JAR files will be found at: {project.dir}/target/webstart

You can copy this directory directly to any web server and point users at the HTML file to run your app. Both the HTML and JNLP files are built from velocity templates which you can customise to be anything you want.

The web-based distribution, and auto updating of Webstart are great in theory, but it doesn’t work that well in practice. Use webstart only if you have control over the operating environment (e.g. you are running within a corporate IT network and can control Java versions, etc). Don’t try to use it for delivery to the general public – it just won’t work and will cause you lots of grief.
 Some other things to be aware of with webstart  depoyment:
  • browser security issues means Java will always be auto-updated, your app may break at any time if a future version of JavaFX changes the way your app works
  • there is a trend away from browser plugins and this option is not likely to be supported on major browsers soon


Native Installers

To build the native installer for your current OS run:

mvn jfx:build-native

Your bundle will be built into: {project.dir}/target/bundles

Currently native installers require you to first manually download and install an extra packaging tool specific to your OS. e.g. on Windows you need to install WiX. See the JavaFX packaging guide for more info.

Native installers are a recent addition to JavaFX, basically wrapping your Java program in a native launcher for your platform (i.e. an ‘exe’ on Windows) and bundling this into a native platform installer (i.e. an ‘MSI’ package on Windows). The JRE is actually co-bundled into the installer so your user just installs your application and does not need to install Java separately. From the end user’s perspective the whole thing is ‘native’ and the fact that your app is a Java app is hidden from them completely.

This is a very powerful option and has a lot of promise (and is the approach I would recommend) but there are still a couple of drawbacks. The main one is that you can only build the distributable for the target platform on that platform, i.e. you can only build a Windows MSI on a Windows machine, and a Mac PKG on a Mac machine. Additionally you have to download and install a third-party packaging tool that the JavaFX packing tool uses under the hood (i.e. on Windows you have to download and install WiX). I am working on extending the Maven plugin to do this last step for you.

The other major drawback is that the JRE is currently very large (70MB+) making your distributables large. This is something the Java community is (very slowly) working on, and once I get the other parts of this plugin working I may also put some effort into fixing this – it should be possible to get the bundle size under 20MB.

Finally there is no auto-updating code as yet, so each release your users must uninstall the old version and install the new one. Again this is something on the JavaFX to-do list but it hasn’t got a lot of attention. If it is something that you want, best to raise it in the open JFX mailing list.

Native installers is where I intend to spend the most effort going forward as I believe it is the only real long term option for JavaFX. I plan to release a version of the Maven plugin that can automatically download WiX for you sometime in the next few weeks. After that I will look at options for doing something similar for Mac and Linux bundles. 

Conclusion

The Maven Plugin makes it simple to get up and running with JavaFX and to build distribution bundles.  Your projects are also IDE independent (i.e. developers can use IntelliJ, Eclipse or NetBeans on the same project without problems) and you get all the cool dependency assistance that has made Maven such a popular tool. There’s little reason not to use it.

The Plugin is quite new however and since I develop on Windows, it has not been tested on Mac and Linux. If you run into any trouble on these other platforms, please raise an issue (general testers on these platforms would be great).

Currently the plugin does not support Applets. This would be trivial to add but since Applets are virtually a dead technology I have not bothered. If this is something you would like to use, raise an issue.

I also have not added Mac/Linux shell script options (i.e. similar to the Windows BAT option). Again these would be trivial to add but I don’t have environments to test on. If you have a need for these, raise an issue (and by doing so you volunteer to be the tester).

Several more advanced features are either missing (e.g. including native third-party libraries) or not well documented (e.g. templating HTML and JNLP files). I will tick away at these as and when I have time and motivation. I’m just one guy working on this in my free time, after-hours though – there’s plenty of work to be done here so if anyone is interested in volunteering some time, let me know.

Continue Reading→