Introduction

JavaFx is a new rich client framework by Oracle. It allows you to create visually pleasing enterprise business applications with the Java language.

While many small demos are showing up in the community, there aren't many articles on how to structure your JavaFx application. Using a good structure makes it easier to maintain your application, add new features and improves overall stability. These are all very important in enterprise applications.
This serie of articles will try to remedy that by showing you one of many ways to structure your application. This is certainly not the only way to do it, but it will give you a starting point. Even this structure is open for improvement (as every structure is).

High-level Overview

The structure I will describe is based on Robotlegs, an Apache Flex micro-architecture library. But instead of using events to decouple the layers, I went with for direct calls (with interfaces in-between). While events allow you to decouple the layers even more, I prefer direct calls with interfaces over events because they make it easier to follow the flow of your application.

The diagram below shows the different components and layers in my architecture. The arrows indicate the dependencies.

View: This is where the JavaFx components are used to build the UI.

Mediator: The mediator facilitates the communication between the view and the application logic layer. This is why it's both included in the view layer as the application logic layer. This layer should not contain application logic, it's just a postman who receives calls from the view and delegates them to the application logic layer and vise versa.

Command: This is where your application logic will reside. A Command is a class which executes a single unit of work and will be disposed when it's finished.

Service: A service is used to access external resources. This can be a remote service, a file on the filesystem or a device attached to the user's pc.

Model: A model stores the state of your application. This can be the selected record which should be accessible in multiple views.

The diagram below shows a sample flow of an application. In this case the user clicked on a button to delete a contact in a list.

The view asks the mediator to delete the item by calling the deleteContact(contact) method on the IContactListMediator interface.

The mediator creates a new DeleteContactCommand and registers a success handler on it. Then it calls the start() method on the command.

The command calls the contact service to delete the contact from the database

The command calls a method on the model to remove the contact from the application state. It receives the updated list of contacts from the model

The command finishes and triggers the registered success listeners. It provides the updated list of contacts to the success handlers.

The success handler in the mediator asks the view to update the list of contacts based on the updated contact list it got from the command.

Used libraries

For my application I didn't use any framework (except for JavaFx, obviously), I wanted to create my own structure without the overhead of a framework. All I used was the JavaFx framework and Guice for dependency injection.
For those interested in build tools, I used the JavaFx Gradle plugin created by Danno Ferrin to create a build script.

Dependency Injection

Mapping your dependencies

A DI library like Guice allows you to inject instances of certain classes into other classes without you having to manually instantiate and inject them. This can greatly improve the quality of your code since you don't have to write all that yourself. Guice is basically the glue that holds your application together.

In Guice you have to create a Module class which defines all the mappings. Such a module class can look like this for a simple application:

So in most cases you will be mapping implementations to interfaces. Always try to use interfaces. This allows you to, for example, create a stub implementation of a service (in this case StubEventService) and a real implementation which you can then just swap by changing the Guice mapping.
Only for the Commands I didn't create interfaces because they wouldn't add that much value. They would all practically be marker services, but you'll see that in my following posts.

While this Module implementation is ok for a small application, it can quickly explode in one huge class when you're building a bigger application. This is where bootstrap classes come in handy. A bootstrap class is just a class which initializes a certain part of your application. In this case it would initialize the mappings of the views, the mediators or the commands. Such a bootstrap class would look like this:

Conclusion

In this post I gave a broad overview of the structure and explained how dependency injection fits into this.
In the following posts I will go into more detail for each layer and give some best practices.
You can find the full sample application here: https://github.com/SlevinBE/JavaFx-structure-demo

Given that the view is defined in a FXML file (or setup manually), then the mediator would be a controller or backing bean. If the "delete contact" button is pressed, for me, the backing bean should do a (skipping null checks):

em.find(Contact.class, 123).remove();

And on success also remove the contract from the list in the backing bean populating the JavaFX ListView control (or maybe do a JPA query to repopulate).

If you want to go enterpricy and move the whole business model onto its own application server, then the backing bean talks to that API directly. Say a REST interface:

If you would do all that in your backing bean then it can become a rather big class, which makes it harder to unit test (more dependencies, more code, ...).Also, you would have to make sure that in your backing bean all the logic/remote calls that can take some time are executed in a separate thread to not block the UI, which further clutters your code. In my approach this is nicely separated in the command layer.

Making sure the UI stays responsive is indeed the responsibility of the backing bean; it knows when it can simply wait or put stuff in a separate thread (and provide a feedback on progress). Of course some utility code to prevent scaffolding is needed, but it's all part of the UI layer. Naturally there should be no business logic in the backing bean, just the code connecting the UI to the model. Any business logic is part of the rich domain model.

About the class growing; kinda depends on the JFX screen, but with loads of controls the backing bean can become bigger, yes. Hard to avoid. The per-control code still remains constrained to max 5 lines or so. On the other hand, a pile of interfaces don't make things more readable either.

@tbee I think we both describe a valid architecture which can be used depending on the requirements of the application. Correct me if I'm wrong, but it looks like you are describing an architecture for a thin client (where the business logic is located on the server), while my architecture is for fat clients (business logic in the client).So in my case the client will be more complex (therefore the command layer), while your solution doesn't need that because the business logic is on the server.

I also thought about best practices for the structure of my JavaFX apps. I fully agree with Ajay V. that the use of FXML Controller classes is (in many cases) a good solution when separating application logic from actual UI elements.

I created a small framework to ease the integration of Guice into your JavaFX applications a while ago (It's called: "fx-guice").

--> https://github.com/cathive/fx-guice

By extending "GuiceApplication" instead of "javafx.app.Application" you gain a bunch of advantages:* You can @Inject your app object anywhere as it will be automatically bound* You can use the GuiceFXMLLoader to load FXML files and use both @FXML and @Inject annotations in your FXML Controller classes* You can use @FxApplicatioNThread to mark methods that must be executed on the JavaFX event dispatch thread* ...

"fx-guice" is published under the Apache License v2.

Source code can be found on Github and ready-to-use artifacts can be found in the Sonatype OSS Maven repository. I also uploaded some (very simple) example apps (e.g. a cute little calculator) that shows how to use my framework.

JavaFx is indeed very powerful (dare I say even more powerful than Flex). It has threads, the JVM languages (Java, Groovy, Scala,...), a build in Web engine (based on WebKit) and is imo architected better than Flex.

I've been following the Apache Flex mailing list, and you're doing some great work on the AS3 -> JS part!

Yeah, just wait to see what is going to be released next week by Mike Laboriola and the gang. (IE Joel Hooks might might be floating around this project as well).

Its something very fun with AS -> JS that you might actually think is quite interesting based on your interests of these types of design patterns.

I have Caustic audio framework;

http://www.teotigraphix.org/causticcore/overview/

That is what I "do", writing a cross compiler is for run. :) So I am making desktop applications to manager mobile audio apps, JavaFX has really blown me away, I thought I was going to have to go back to 2002 and use Swing! :)

I really like the way you structure the code. It's very clean, testable and easy to maintain. Besides the possibility of using some other posted libraries - I got a simple question.I've taken a look at the github repository - you're defining VOs (I guess View-Objects). How can this work together with persistent frameworks. I can't imagine any other possibility then converting the given VO to a POJO or direct sql - which both adds a lot of unnecessary code.

The sample was made for a client-server architecture, so the client won't persist anything, that's the server's responsibility.So the server and client use VO objects to transfer data. The server will convert (e.g. Hibernate) mapped POJO's to VO and vise versa. This does indeed lead to a lot of extra code (in the form of mapper classes), but this is where mapper libraries like Dozer (http://dozer.sourceforge.net/documentation/gettingstarted.html) can help with.It also has a couple of important advantages: 1. you can't get lazy initialization exceptions.2. The view only gets the information it needs and in the format it wants to use it.

But if you have a simple application which needs to persist something to the database which doesn't necessarily requires a server, then feel free to replace those VO's with mapped POJO's and create a service in your client which persists these.

So in the end it all depends on the type of application you want to build. For example this architecture is a fat client architecture, but if you want to keep your business logic on the server (thin client architecture) there may be better client architectures.

Because this was the most straightforward way to do it, I didn't want to make the initialization process more complex than it should be.If you look at it from a purely architectural/theoretical viewpoint you are indeed correct that this could be better initialized somewhere else. However, sometimes I weigh the cleanest solution to the amount of complexity it adds, and in this case I thought it wasn't worth it.

Every JavaFx developer recognizes a Main class (or any class that has a main method and which extends Application) as the entry point of a JavaFx application. That's also why I do it in there because in most cases this class won't contain all that much code.

Awesome stuff, i used Robotlegs in tons of Projects and was looking for a similar aproach in JavaFX. Thats perfect. Not quite the same without the event dispatching stuff, but close.I also like building components in Flex better then JavaFX, but overall, its pretty much the same stuff.Still, love Flex and always will :D