Upgrading to Vaadin Framework 8 (Part 1 of 2)

With a major release, you would usually expect major modifications in the core of the framework. But this time, the migration is not too complicated. Not only because of the migration tool provided to make a smooth transition from Framework 7 to Framework 8, but also because of the similarity in many of the components’ APIs.

A good upgrade strategy is needed though, and I summarize them under the following headlines:

  1. Upgrade dependencies in the POM file
  2. Run Maven goal vaadin:upgrade8
  3. Upgrade Add-ons
  4. (Soon, in part 2) Upgrade non-data components
  5. (Soon, in part 2) Upgrade data components


I decided to try those steps live in front of the camera, while upgrading an enterprise application, to present the challenges that I will face and show how to solve them.

Prepare your popcorn, gather all your Vaadin experts, and let’s watch the first part of upgrading a Vaadin Framework 7 application to Vaadin Framework 8 application – in real time!

During this part, I will cover the first and most important three steps. With those steps you get a working application that compiles, is production ready, and uses the latest version of Vaadin Framework 8.

After completing the video, your application is actually using Framework 8 and you can start using the new components and APIs when building new parts of your project.

To summarize the main steps, and fails, done in this video; first of all, it’s important to familiarize yourself with the migration guide documentation and then follow the steps:

1. Upgrade dependencies in the POM file [08:48]

It’s obvious that we need to change the dependency from version 7.x to 8.x, but we also need to check other changes in the dependencies. We need to use the compatibility packages to maintain a smooth and slow transition from old components to newer ones, without breaking a lot of code. We may also add some new parameters, such as widgetset.mode (which was technically added in Vaadin 7.7 releaser).

I’m doing this by comparing with the POM file of a sample project created for Framework 8, to see the differences with my own project’s POM file.

2. Run Maven goal vaadin:upgrade8 [19:31]

Eventually the first step will produce a lot of errors because of the newly introduced libraries and packages. Luckily there is a simple tool provided with Framework 8 that helps you to fix most of the broken packages. To use this tool, simply run:

mvn vaadin:upgrade8

This goes through your source code and changes all those Vaadin imports, which have incompatible changes, to use the versions from the compatibility package. To get the remaining compilation errors fixed, there may be a couple of small changes you’ll need to do manually, like changing into using the new ContentMode enumeration in Label components.

3. Upgrade Add-ons [21:49]

Unless you are using vanilla Vaadin Framework, without any external dependencies, you will eventually run into this problem. And I have to say that this is the trickiest and most complicated part of the migration. Let’s divide the Add-ons into 5 categories:

3.1 Pro Tools:

They are fully migrated and fully supported in Framework 8. Jump to this section of the migration guide and you will find important details on how to perform the migration.

3.2 Official Vaadin Add-ons:

They are also fully migrated and fully supported in Framework 8. All you have to do is to check the latest version from the directory, and update the corresponding version in your POM file dependencies. Some other official add-on versions are provided inside the BOM, and you just need to remove the version number from the dependency section, such as Vaadin CDI, and Vaadin Spring.

3.3 Integrated Vaadin Add-ons:

Vaadin Icons Add-on is now part of the core Framework 8. If you were using it, then remove the dependency from your POM file, remove the old imports from your source code, and make them point to the new package coming from the core framework:


3.4 Migrated Community Add-ons:

Many add-on developers have migrated their add-ons to Framework 8 already, which is great! Check the directory to see the version number for Framework 8 compatible versions and possibly other documentation provided by the developer on how to perform the upgrade. In many cases all you have to do is to upgrade the version. In some cases, especially in data related add-ons, when you need to provide a compatibility layer to work with old Framework 7 data binding APIs, you might need to make a manual modification to get them to work.

One example is the Viritin add-on used in this project: Matti - the add-on maintainer - provided a compatibility layer similar to the one in the core framework, to make it possible to use the latest version with Framework 8, while keeping the old Framework 7 data binding code. All you have to do is to change the package import from:


The migration tool will not automatically take care of those, and you need to fix them all manually.

3.5 Non-migrated Community Add-on:

The most unfortunate situation is that you have a dependency to an add-on that is not yet upgraded to Vaadin 8. Your hope is not lost yet. You have a couple of options you can do:

  • Ping the developer e.g. via GitHub and let him/her know that there is a need for Vaadin 8 compatible version. But be polite and understand that he/she is most likely not doing this for money.

  • Help the maintainer to do the upgrade. You can fork the project, do the upgrade and use a local build in your application. And finally, create a pull request to the original developer, so that a new version could be available for the rest of the community.

  • You can also try to urge other community members to help with the upgrade in the forum, here in the comments section, or on GitHub. Or if you have some budget to spare, ask, for example, Vaadin’s experts to do the upgrade for you.

  • You can also try to search for an alternative add-on from the Directory, or see if you could do without it now with Vaadin Framework 8.

At this point, you will have a fully working Framework 8 based project. You have done the biggest and most complicated part of the migration. In the next part of this blog, I will explain how to migrate to newer components and how to deal with new data binding APIs.

Is there an Add-on that you wish to see migrated to Framework 8?

Did you perform the first three steps mentioned here and are still getting errors, or the project does not compile still?

Anything else not working with the migration?

Let us know in a comment below!

Part 2 coming soon!

The new and fully customizable In-House Training is out!

Improve your skills whenever and from wherever you want.

We are proud to present our new and fully customizable In-House Training. Benefit from a live and Vaadin Expert-led training for up to 16 attendees in a location of your choice.

What is included?

The new In-House Training can be fully customized to your own specific needs. You can freely choose each of the 30+ courses from our current training offering and tailor the training experience to the needs of yourself and your team. The training modules vary in skill level and time. Topics are ranging from basic Vaadin courses over migration courses and CDI courses to PWA based courses to improve the skills of you and your team. All interactive courses contain theory slides, hands-on coding exercises and material handouts.

Get an overview of our course offering

Where is the Value?

You and your team will learn directly from the people that have built Vaadin’s  framework, components and tools. No matter if you are kickstarting a new project or you are part of an experienced team, you will profit from the unique advantage of discussing Vaadin details within your own and specific project context directly with the trainer. With the knowledge obtained in the in-house training you’ll get to know how to integrate Vaadin with existing technology stacks and how to boost your productivity.



What does it cost?

The Vaadin In-House trainings have fixed prices per day and team size. Trainer expenses such as traveling, lodging and more are all included in the fixed price. All signups before the end of July will receive an additional 10% release discount.

For more information contact us directly


Client-side fail-over

Traditional clustering solutions focus on performing clustering tasks purely server-side. The browser only possesses one URL (one IP address) after all, so there is not much we can do (well, there is, but more on this later). Usually, the intent behind clustering is twofold:

  1. If one server computer crashes, the server-side setup is configured to redirect the traffic to another server computer. This is called failover.
  2. If one server computer is under heavy load, another server computer can share the load. This is called load-balancing.

Naturally, there must be some network gizmo in front of those servers - all incoming traffic is routed to a single IP by the browser after all, so there must be a special computer acting as a load balancer present there. This load balancer talks to the servers, monitors their load (and whether they are alive) and passes the traffic through to the least loaded server. Usually, this is Apache with mod_proxy or some other software-based solution; more expensive setups take advantage of hardware load balancers. The load balancer should have the following properties:

  1. The load balancer must be extremely resilient to failures - it is a so-called single point of failure after all, that is, when it crashes, it’s over and the whole cluster is unreachable. There is a technique where two computers compete for the same IP - only one succeeds and the second one just waits until the first one crashes, then takes over the IP.
  2. Different servers hold different http session objects in-memory. If the load balancer would just randomly route requests, this would cause random modifications of random sessions. Since copying a session throughout the cluster after every request is not cheap and would require cluster-wide locking, another approach is usually taken: when the user logs in, the load balancer picks a server and from now on it will route the traffic to that very server only.

The trouble with server-side clusters

Unless you are an administrator guy trained to set up a cluster of a particular web server, the cluster is not easy to set up (and most importantly - test, so that you gain confidence that the cluster actually works and performs its duties, both failover-wise and load-balancing-wise). Even the simplest options of having a group of JBosses with a special RedHat-patched Tomcat as a load-balancer (so that it can talk to JBosses and monitor them for load) takes some time to set up. Not to mention testing - often it is easier to just take the leap of faith and hope the cluster works as expected ;-)

So, for small projects clusters are often overkill; not to mention that there is this single-point-of-failure (load-balancer), unless you do an even more complex setup of having two load-balancers competing for one IP address.

What about other options?

Is it possible to get the failover/load-balancer properties some other way? How about if the browser took the role of load balancing? Obviously this is a great single-point-of-failure - when the browser crashes, it is clear to the user that she can’t browse the web until she starts the browser again. Naturally, the browser cannot possibly know the load on the servers so it can’t act as an informed load-balancer, but what about the browser doing the failover at least?

It is actually possible to bind multiple IP addresses to a single DNS record. The DNS server may then shuffle or rotate the IP list (so-called DNS round-robin), so that different browsers will try different IPs in a different order. With thousands of browsers, this works surprisingly well and the load is distributed more-or-less evenly amongst the servers. Looks great, right? Unfortunately, it isn’t. The trouble is the session. The browser is free to switch IPs often, even on every request, and if the session is not distributed amongst the computers in some way, then this approach won’t work. And distributing a session requires a server-side cluster, which we wanted to avoid. So, any other solutions?

Maybe we could implement a load-balancer inside the browser. How? JavaScript.

JavaScript-based load-balancer

The idea is simple. Publish your servers under multiple DNS names, e.g.,,, etc. Then, once the browser visits, along with the page it will download a special javascript code containing a list of all the servers.

Then, in case of server crash, just let that javascript code redirect to another DNS. Simple, right? Let’s discuss this a bit:

  1. This approach will force the server to always communicate with a single server, thus avoiding the necessity to distribute the session. Of course, when the server crashes, the session is lost and there is nothing we can do about it. However, clusters also tend to have trouble replicating sessions big enough (and with Vaadin it is easy to have a session as big as 200kb-1MB and more per user). It is usual that when fail-over happens, the session on the spare node may not be up-to-date, but in fact may be several minutes old, depending on the cluster configuration. This may be acceptable though; but often it is tolerable to lose the session in the event of crash.
  2. This client-side approach is so easy to test - the testing itself is almost not required. The whole load-balancer is implemented and tested by Vaadin; you only need to supply a valid set of URLs.
  3. The primary page is always downloaded off the, thus creating a heavy load on that server. This could be remedied - if a random redirect is performed by the javascript load-balancer initially, to move away from the main server, this will distribute the load evenly.
  4. Failover is performed by the browser, which is maintained by the user. Win!
  5. This approach is not so simple to use in a regular web app, but it is so totally simple to use with Vaadin it is almost a miracle. It requires no specialized infrastructure server-side; you can deploy different web servers on different OSes if you so wish; you can deploy the application cluster-wide any way you see fit - ssh, Puppet, samba share, anything.
  6. The session does not need to be serializable; saving the session to disk can be turned off, thus improving performance.

So, how is this implemented in Vaadin? In Vaadin there is a reconnection dialog, appearing every time a connection is lost. We have just equipped the dialog with the failover code, so that in case of server crash the dialog will automatically redirect to the next server. This is exactly what the following extension does:!addon/failover-vaadin Just include the extension in your app and you are all set. Now *this* was simple, huh? You can watch the extension in action in the following Youtube video. The video shows launching of four independent Jetty instances in Docker on four different ports, 8080-8083.

There are obvious drawbacks to this solution. If the is down, there is no way to download the JavaScript with the additional server list. So this kind of becomes single-point-of-failure. This could perhaps be remedied by employing the offline mode in HTML5, but this needs investigation. But if this was possible, the browser would only need to download the JavaScript once; since then it would be present in your browser, and will thus be able to find a live server even when the primary one is dead.

Downsides of browser-side load-balancing and failover:

  1. The JavaScript load-balancer can not possibly know whether the cause of the connectivity loss is the crash of the server or the loss of the network. It may guess - if you get a connection rejected within 1 second, then probably the server has crashed. If you have connection timeout, then the network may be down or the server may be under a heavy load. So, at some point it needs to ask the user to either reconnect to a spare server, or keep waiting. This needs investigating.
  2. DDOS attack. There is no load-balancer computer trained to divert DDOS; also DDOS may target and overload individual servers, not completely trashing them but making them really slow to respond. It might be possible to prepend the webapp with some sort of DDOS Filter though.

So, if you are willing to sacrifice the session in case of crash, this solution may be perfect for you.