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:

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:

org.vaadin.teemu.VaadinIcons

To:

com.vaadin.icons.VaadinIcons

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:

org.vaadin.viritin.fields.*

To:

org.vaadin.viritin.v7.fields.*

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!

Check out Part 2!