Migrating from the JavaFX Preview Release

Now that the JavaFX 1.0 Release is out, it is time to dust off all your old JavaFX code and fire it up, right?  Well, not quite…  There were a whole lot of changes in the span of a few months, and it is guaranteed that your program will need a little TLC before it runs.  Fortunately, I’ve already gone through this pain on a relatively large codebase (WidgetFX), and can share what I learned.

Language Changes

• Change “attribute” to “var”/”def” – There is no more attribute keyword, but it is a simple search and replace to change it to var everywhere.  On a second pass you might want to convert vars that are never changed to def for efficiency.
• No More “static” – If you want to make a variable or function as static, just move it outside your class declaration.  If it is declared public you can access it from anywhere else just by prefacing it with the file name, no static modifier needed.
• New Access Modifiers – The default access modifier was changed to private rather than package, so you need to change any attributes or functions that had no modifier to package and then can delete all references to private.  On a second pass it may be a good idea to button-up permissions by using the new public-init and public-read permissions.  Here is a quick-reference table:
  

  Preview	1.0	Migration
  private	default	Remove this keyword everywhere
  default	package	Add package anywhere no modifier was specified
  protected	protected	No change
  public	public	No change
  N/A	public-init	Use this anywhere the user should be able to initialize and read, but not update
  N/A	public-read	Use this anywhere the user should be able to read, but not initialize or update

• Required “override” – It is now mandatory that you use the override keyword on any member variable or function that exists in the superclass.  Expect to be going through lots of compiler errors to find all the places you need to fix this…
• {} Instead of “+” for Concatenating Strings – While the java-esque “+” operator for concatenating strings was an easy habit to fall into, it is no longer valid.  Instead you have to use the {} syntax to build strings.  For example, rather than “hungry for: ” + meat, you would write “hungry for: {meat}”.
• Keyframe Syntax – While this is not required to get your code working, there is a new KeyFrame syntax for doing animation that has the potential to make your code much shorter.  Rather than creating an instance of the KeyFrame class you can simply write “at (duration) {x => y}”.

On Applications, Stages, Scenes, and Nodes

All your previous conceptions of what the terms application, stage, and scene meant have now been blown away.  For those of us who got very wired in to the old terminology, here is a quick reference from the old to the new:

Preview	1.0	Explanation
Application	Stage	A Stage is now the top level container, which creates a Frame when run stand-alone or becomes the content area in an Applet.
Stage	Scene	The Scene is a grouping of Node content that can be added to a Stage.  It has some useful properties including the stylesheet.
Node	Node	Nodes remain largely unchanged, and are the base class of everything else that is visible in JavaFX.

Note that you can return a Stage, Scene, or Node from your main class and they will all work within an execution context (such as an Applet).

Some things to note:

• How do I size my window? – If you want to set the outer bounds of the window, you can use the Stage width and height.  Just remember that the window decoration will reduce the content area left.  You can also set the Scene width and height, which will correctly size the window for the contents (including decorations).  Unfortunately you can only do this once, because they are public-init variables.
• Accessing the Window – For some advanced functionality you may need to get direct access to the java.awt.Window instance underlying a Stage.  This has been taken out of the API, but I put together a utility class in JFXtras called WindowHelper that works around this issue.
  • Note: if there is anything you need to do directly on a Window class, raise it to the JavaFX team so they can make sure it gets added in a future release.

Where did my class go?

There were a lot of package name changes, and while you can probably dig around in the API docs and find most of what you want, it is good to have an idea about the main changes.

Here is a quick package migration guide:

Preview Package	1.0 Package
javafx.application.*	javafx.stage.*
javafx.scene.geometry.*	javafx.scene.shape.*
javafx.input.*	javafx.scene.input.*
javafx.lang.Sequences	javafx.util.Sequences

API Changes

There are way too many API changes to hit everything, but here are a few that are common or relatively hard to track down:

Swing changes:

• Swing classes extend Node, no need for ComponentView
• All the Swing class names have “Swing” appended in front (e.g. Slider is now SwingSlider)
• No more containers or layouts (see the omissions section below)
• Wrapping a Swing component is now accomplished via SwingComponent.wrap()

Graphics:

• Horizontal/VerticalAlignment are gone, use a translation with a bind expression instead
• FontStyle is gone and replace by properties on the Font class
• Number is used almost everywhere now rather than Integer

Animation:

• The start() method has been renamed to play()
• autoReverse vs. rate – Previously, the only way to reverse an animation on subsequent runs was to set autoReverse to true.  Now you can (and have to) use rate to control the direction of the animation by setting it to 1 for forward and -1 for backward.

Getters replaced by vars:

• MouseEvent.getButton() -> MouseEvent.button
• MouseEvent.getStageX() -> MouseEvent.sceneX
• Node.getWidth() -> Node.boundsInLocal.width
• etc.

Miscellaneous:

• __ARG__ -> FX.getArguments()
• System.out.println -> println() (builtin)
• System.exit(0) -> FX.exit()
• DeferredTask -> FX.deferAction()

Some noticable omissions include:

• Dialogs – SwingDialog is gone and there is no equivalent yet.  Fortunately, I did the hard work and hacked a Dialog replacement (that extends Stage) which you can get as part of the JFXtras project.  It includes support for parent windows, modality, alwaysOnTop, and even auto-size via a “pack” option.
• Layout – ClusterPanel and the rest of the Swing containers are gone.  The only layout classes that ship as a part of the 1.0 release are HBox and VBox, which are useful, but not nearly enough.  Until they release some official layouts, there is a Node-based Grid layout implementation in the JFXtras project.

New and Noteworthy

• Reflection – The new JavaFX reflection APIs are very powerful.  They are not for the faint of heart, and have minimal documentation, so this may be a good future blog item.
• CSS Styling – The new CSS styling support will help bridge the gap between designers and coders.  Same comment about lack of documentation, but it is fairly intuitive once you start using it.
• Transitions – There is a whole new transitions package that makes it even easier to do common animations.  Give it a try!

In Summary

I still have nightmares about painstakingly going through thousands of compilation errors in my code.  Just when I thought I had caught the last one, another few files started compiling and I was buried all over again.  Hopefully through my trial-and-error you will save a few sleepless nights.

Did I catch everything?  Hell no!  But this should be enough help you to get over that initial adoption hump.

Good luck!