Most Vaadin Framework 7 applications will need some changes when migrating to Vaadin Framework 8. To make migration from version 7 to 8 as straightforward as possible, Vaadin Framework 8 ships with compatibility packages that include all the old features and APIs that have changed between versions.
The recommended migration path to take for any non-trivial Vaadin application is to first switch any incompatible components to using the APIs available in the compatibility packages, after which parts of the application can be migrated separately. This is primarily to get an existing Framework 7 project up and running with Framework 8 as quickly as possible, as well as to avoid having to switch to using completely new APIs throughout an entire project all at once.
The very first step in migration is to ensure that your project is configured to use Framework 8 dependencies, as well as include any of the desired compatibility packages needed in your migration. Also note that Framework 8 requires JDK 8 for development. For deployment configurations, refer to the list of supported technologies in the release notes, available at https://vaadin.com/download/release/8.0/8.0.0/release-notes.html#supportedversions.
For maven based projects including compatibility packages is simply a matter of changing the artifactId of the desired non-compatibility dependency to the compatibility variant. For example in the case of changing the vaadin-server dependency from Framework version 7.7.6 to 8.0.0 would require changing
<dependency> <groupId>com.vaadin</groupId> <artifactId>vaadin-server</artifactId> <version>7.7.6</version> </dependency>
<dependency> <groupId>com.vaadin</groupId> <artifactId>vaadin-compatibility-server</artifactId> <version>8.0.0</version> </dependency>
for including both compatibility features as well as non-compatibility ones, or alternatively
<dependency> <groupId>com.vaadin</groupId> <artifactId>vaadin-server</artifactId> <version>8.0.0</version> </dependency>
to only include Framework 8 features. The full list of compatibility packages available for Framework 8 are the following:
|The themes Reindeer, Runo, Chameleon and Base have been deprecated in Vaadin Framework 8 and they now reside in the compatibility-themes package. Applications still using any of these themes must include this package.|
For migration of projects using Vaadin Pro Tools check the following sections:
As with projects themselves, some addons built for Framework 7 will not be directly compatible with Framework 8, thus any add-on dependencies must also be updated to versions that are compatible with Framework 8. Be sure to check the add-on directory at https://vaadin.com/directory for updates to add-ons your project depends on.
For add-on developers, the same steps outlined in this guide can also be applied to upgrading your add-ons from Framework 7 to 8.
Once your project’s dependencies have been updated for Framework 8 migration there are a few steps to begin using the compatibility versions of the old APIs, namely changing of imports and ensuring that your widgetset is correctly set up. Optionally, if you are using Vaadin Designer or declarative files otherwise, the tag names for compatibility components need to be updated.
To ease the migration process, the Vaadin maven plugin has a target
vaadin:upgrade8 which updates all
imports in java files and prefixes in design files to point to the versions in the compatibility packages.
This migration tool is available separately at https://github.com/vaadin/framework8-migration-tool.
The only change to classes in the compatibility packages is the change in their classpath. All compatibility classes can be found under
For example the compatibility
TextField is available through the import
import com.vaadin.v7.ui.TextField, given that the project dependencies have been set up to include the compatibility variants, as described in the previous section.
When using compatibility packages in your project you need to changes references from the default Vaadin client side widgetset
com.vaadin.DefaultWidgetSet to the one containing the compatibility packages
com.vaadin.v7.Vaadin7WidgetSet, which is available in the vaadin-compatibility-client-compiled maven dependency.
Typically, widgetset recompilation will handle this automatically for you, except for the following two cases which should be handled manually:
Your project defines a custom widgetset, in which case you need to make sure
An UI in your project defines its widgetset with the annotation
@Widgetset("com.vaadin.DefaultWidgetSet"), which should be changed to
The widgetset compilation for
Using components from the compatibility packages in your declarative files only requires you to change the prefix from
vaadin- or alternatively
For example, the conversion of a
<vaadin-text-field _id="textField" />
to its compatibility equivalent,
com.vaadin.v7.ui.TextField, would simply be achieved with the following replacement
<vaadin7-text-field _id="textField" />
in the corresponding design html file.
By replacing incompatible components of your application with ones from the compatibility packages your project should now be in a state where it can be compiled and run. To get started with using the new Framework 8 features it is now only a matter of replacing the usage of compatibility APIs where desired.
Aside from minor API and default changes at the component level, the largest change in Vaadin Framework 8 is its new data model.
Framework 8 no longer uses
These building blocks for the old data binding have been deprecated in favor of more Java 8 friendly APIs.
The new data model can be roughly split into three main topics, namely binding data to field components, providing data to listing components and handling selections. The revised "Binding Components to Data" chapter is the recommended resource to get started with learning these new concepts. For migration from Framework 7 the key references are the following sections:
"Showing Many Items in a Listing", which covers the new
DataProvider, as well as the associated sorting and filtering APIs.
And for the new selection APIs, "Selecting Items".
For a full list of incompatible changes between Framework 7 and 8, please refer to the Incompatible or Behavior-altering Changes section of the release notes, available at https://vaadin.com/download/prerelease/8.0/8.0.0/8.0.0.beta1/release-notes.html#incompatible.