Migration from 11 to version 12

A migration to RapidClipse version 12 consists of two steps. The first is to run the automatic migration within the IDE and the second is to check each item below to see if everything is ready for version 12. Please always make sure you have a backup, such as your GIT or another solution.

Step 1 - Preparation:

  1. Download the latest RapidClipse IDE and extract it to a folder of your choice.

  2. Create a new workspace.

  3. Import your project into this workspace and create a new branch to perform the migration.

  4. Check all basic configurations within the new IDE, some examples below:

    1. JDK versions of your IDE

    2. Export/import your database connections from your old IDE to the new one.

    3. Copy your code formatter settings

    4. Install all of your previous plugins such as JRebel.

    5. Install a suitable application server such as Tomcat 9.

  5. Make sure there are no compiler errors in your project.

Step 2 - Automatic migration:

  1. There are two different ways to start the upgrade:

    1. At IDE startup you will be prompted to update a specific project.

    2. In Project Management: Right click on the project > RapidClipse > Update Project

  2. The following changes should be done after the migration:

    1. Changes within the POM.XML

      1. All dependencies related to the RapidClipse framework should be updated to version 12.0.0

      2. Vaadin-maven-plugin should be updated from 14.8.4 to 23.3.25

      3. Added dependency jakarta.servlet-api version 4.0.4

    2. Some new files should also be created.

      1. From Vaadin 15 there is a new interface called AppShellConfigurator. This means that every Vaadin project should have a class that implements this "AppShellConfigurator". During the automated migration, a class called "AppShell" will be created that implements the interface. In some rare cases, this class may not be created automatically. If not, simply copy it from a newly created empty project or create it yourself. See the Vaadin documentation for more details: https://vaadin.com/docs/v23/advanced/modifying-the-bootstrap-page

      2. Some new entries are added to the “.gitignore” file.

Step 3 - Manual Migration

  1. Move Vaadin annotations to the new AppShell class:

    From Vaadin 15, all Vaadin annotations like @Push or @Theme have to be placed in a "app shell class". Such a class was generated in "automatic migration" step. See here for a listing of related Annotations and further info.

  2. Remove PageConfigurator interface and related method from MainLayout class if present.

  3. Move existing content of AppBootstrapListener class to the new AppShell class. See: https://vaadin.com/docs/v23/advanced/modifying-the-bootstrap-page#the-appshellconfigurator-configurepage-method

  4. For further instantiation which has to be done on session init or servlet init use VaadinServiceInitListener or ServletContextListener

  5. Update @Theme annotation:

    1. If you are using vaadin’s default themes: @Theme(Lumo.class) / @Theme(value = Lumo.class) needs to be changed to @Theme(themeClass = Lumo.class)

    2. If you are using a custom theme, @Theme(themeFolder = "my-theme") needs to be changed to @Theme("my-theme") or @Theme(value = "my-theme")

  6. Update your CSS.

    There are a lot of changes regarding application styling: changed selector names, changed component inheritance and so on. Please update your CSS files according to the list of changes here.

  7. See also Vaadin instructions to upgrade from 14 to 23

    1. https://vaadin.com/docs/v23/upgrading/essential-steps

    2. https://vaadin.com/docs/v23/upgrading/recommended-changes

Step 4 - Clean Project

  1. Delete “.target” folder

  2. Delete “node_modules” folder

  3. Call maven target “vaadin:clean-frontend”

After cleaning the project and doing all that deletion stuff a restart of the UI Designer or the project with Tomcat need 2 to 4 Minutes to fill the PNPM dependency.
We therefore ask you to be patient.

If UI Builder does not start after the migration, please open the DesignerServer console. There you can often see what exactly the problem is, e.g. at this case:

snippet from console: Forgot to remove "PageConfigurator"
...
Caused by: com.vaadin.flow.server.InvalidApplicationConfigurationException:

The `PageConfigurator` interface is deprecated since Vaadin 15 and has no effect.
Please, configure the page in com.company.example.AppShell, and remove the `PageConfigurator` from:
 - com.company.example.ui.MainLayout
...